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Preface 


About This Manual 


This is a reference manual for the Applesoft BASIC programming 
language as implemented on the Apple lie computer. It is intended for 
readers who have had some previous experience with programming, 
either in BASIC or in some other programming language. It assumes 
that you are familiar with the material in the Apple He Owner's Man¬ 
ual, and if you are a novice programmer, that you have read the Apple 
I le Applesoft Tutorial. 

To make using this manual easier for you, we have divided it into two 
volumes. The complete table of contents, chapters one through eight, 
and the complete index appear in volume one, the volume you are 
now reading. Volume two holds the appendices and the glossary: the 
Index is also included in this volume for your convenience. 

Purposes of This Manual 

This manual has four purposes: 

• To serve as a complete reference manual to the Applesoft BASIC 
language for the experienced programmer. 

• To provide clear enough explanations and examples so that a 
new programmer can learn the details of any statement quickly 
and easily. 

• To allow any reader, even one who is not trying to learn Applesoft 
in detail, to get a general feel for the language. 

• To provide an introduction to program planning, design, and de¬ 
velopment for the programmer-in-training. 

This manual is decidedly not a tutorial. Experienced programmers 
can learn a great deal about Applesoft by reading it from the first 
page straight through to the end; but it wasn’t designed to be used in 
that way. 
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Where to Learn More 

The following sources contain further information about the Apple lie 
computer in general and the Applesoft programming languagej in 
particular: 

• The Apple lie Owner’s Manual covers the basics of the system 
and includes a special section on the Apple lie’s keyboard It 
also contains a list of books and magazines of special interest to 
Applesoft programmers, as well as a short guide to the rest of 
the extensive documentation that comes with your Apple He. 

• APPLE PRESENTS...APPLE is a training disk that comes 
with all disk-based Apple Me systems. It contains an interactive 
tutorial program giving you hands-on practice with many of 
the concepts discussed in the Apple He Owner’s Manual. It’s a 
must if you’re new to computers. 

• The Apple He Applesoft Tutorial is an excellent guide for be¬ 
ginning programmers. It provides introductory, step-by-step 
guidance for the new programmer and has a special chapter on 
editing Applesoft programs. 

• Apple Backpack: Humanized Programming in BASIC, by Scot 
Kamins and Mitchell Waite (BYTE/McGraw-Hill Books) fills the 
gap some newer programmers may feel between the Applesoft 
Tutorial and this reference manual. It teaches programming in a 
friendly and easy-paced way for people who are not computer 
experts. 

• The Apple He Reference Manual contains a wealth of informa¬ 
tion about the more technical aspects of the system’s operation, 
with lists of various programmer-accessible system flags, point¬ 
ers, and soft switches. 

How This Manual Is Organized 

This manual has 8 chapters, 14 appendices, a glossary of terms, an 
index, and a quick reference card. All of it is designed to help you get 
the most out of Applesoft. Here’s a description of what each chapter 
and appendix is about: 

Chapter 1, “General Information,” contains information every Apple¬ 
soft programmer needs. It discusses the programming environment 
in which Applesoft operates and tells how to create, modify, execute, 
and store Applesoft programs. 
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Chapter 2, “Variables and Arithmetic,” deals with some of the most 
fundamental concepts of Applesoft programming: variables, arithme¬ 
tic expressions and operators, arithmetic precedence, Applesoft’s 
built-in functions, and how to define and use your own functions. 

Chapter 3, “Control,” covers the various statements available to di¬ 
rect the flow of program execution. It includes information on uncon¬ 
ditional and conditional branching, loops, subroutines, error handling, 
and program termination. 

Chapter 4, “Arrays and Strings,” completes the material on variables 
begun in Chapter 2. It includes information on the definition and use 
of arrays in Applesoft and on the various string manipulation facilities. 

Chapter 5, “Input/Output,” describes Applesoft’s facilities for getting 
information into and out of programs and for formatting the way infor¬ 
mation is presented on the display screen. 

Chapter 6, “Graphics,” tells how to create, change, display, and store 
low- and high-resolution graphic designs. There is an extensive dis¬ 
cussion on creating and using shape tables, as well as examples of 
how to create animation sequences. 

Chapter 7, “Utility Statements,” contains information on a variety 
of miscellaneous Applesoft facilities for low-level control of the 
programming environment: directly accessing specific memory 
locations, controlling the limits of program space, and tracing the 
execution of a program for debugging purposes. 

Chapter 8, “Bringing It All Together,” is more tutorial than any other 
chapter in the manual; it describes and demonstrates a method for 
planning, designing, and developing efficient, bug-free (well, rela¬ 
tively bug-free) programs. 

Appendix A, “Summary of Applesoft Statements and Functions,” 
gives an abbreviated description of each Applesoft statement and 
function, together with a reference to the chapter, section, or appen¬ 
dix where you can find more detailed information and examples. 

Appendix B, “Syntax Definitions,” defines terms used in the formal 
syntactic definitions of Applesoft statements given in Appendix A. In 
the body of the manual, statement syntax is shown by example rather 
than by formal definition; most readers can safely avoid the formal 
definitions altogether. 
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Appendix C, “ASCII Character Codes,” contains a complete listing of 
the ASCII characters; it is an adjunct to the comments on ASCII in 
chapter 4. 

Appendix D, “Reserved Words,” is a list of words (some of them 
rather odd-looking) that cannot be used in variable names. 

Appendix E, “Error Messages,” describes the meanings of the error 
messages that Applesoft displays on the screen. Each description in¬ 
cludes an explanation of why the error occured; in some cases, there 
are suggestions for debugging. 

Appendix F, “Peeks, Pokes, and Calls,” deals with low-level access 
to features of the Apple lie computer via Applesoft’s PEEK function 
and POKE and CALL statements. There are sections on screen 
text, the keyboard, graphics, miscellaneous input and output, and 
error handling. 

Appendix G, “Hints for Program Efficiency,” offers techniques for 
cutting down the size of programs and for speeding up program 
execution. 

Appendix H, “Implementation Details,” contains information of inter¬ 
est mainly to the advanced programmer. Included here is a memory 
map with a list of pointers and their descriptions, information on 
Applesoft’s methods of internal storage allocation, an outline of its 
usage of special locations in page 0 of memory, and a list of the 
tokens it uses for internal representation of keywords. 

Appendix I, “Display Formats for Numbers,” describes how Applesoft 
displays numbers on the screen and gives the ranges of numbers the 
system is capable of handling. 

Appendix J, “On-Screen Editing and Cursor Control,” contains tables 
summarizing Applesoft’s on-screen editing features. 

Appendix K, “40/80-Column Differences,” is a table showing the dif¬ 
ferences in Applesoft’s behavior with and without the optional Apple 
lie 80-Column Text Card installed. 

Appendix L, “Comparison with Integer BASIC,” gives charts showing 
the differences between Applesoft and Apple Integer BASIC and 
discusses how to convert Integer BASIC and non-Apple-lle BASIC 
programs Into Applesoft. 
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Appendix M, “If You Have a Cassette Recorder,” describes Apple¬ 
soft’s statements for using tape cassettes as a storage medium for 
programs and information. 

Appendix N, “Complete Listing of the Postage Rates Program,” 
gives the complete text of the programming example developed in 
Chapters. 

At the back of the manual is a Glossary of technical terms. In general, 
buzz words are no-no’s in this manual; but any technical field has its 
own jargon, developed out of necessity to describe concepts genu¬ 
inely having no parallel in common language. The glossary lists all 
(we hope!) such words and terms that have found their way into the 
manual, and a few others besides. 

A tear-out Quick Reference Card, designed to act as a “memory jog,” 
gives an extremely brief description of each statement, function, op¬ 
erator, and variable type. 

How to Use This Manual 

Here are some suggestions on how to use this manual, depending on 
the particular goals you are trying to accomplish. 


As a Reference 

• Look up the feature of interest on the Quick Reference Card; 
each statement, function, operator, and variable type is listed 
there in an extremely abbreviated form as a “memory jog.” 

• Look up the feature in Appendix A, “Summary of Applesoft State¬ 
ments and Functions”; each statement and function is described 
briefly, and a reference is given to the chapter, section, or appen¬ 
dix where it is discussed in detail. 

• Look up the feature in the index; there you’ll find references to 
the places in the manual where it is mentioned. 

• Look in the appendices at the back of the manual for quick refer¬ 
ence on specific facts. 
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To Learn the Applesoft Language 

• Read Appendix A, “Summary of Statements and Functions,” to 
get a quick feel for each of the features in the language. 

• Read through each chapter and enter and run the example pro¬ 
grams: then try modifying them to check your understanding and 
gain hands-on experience. 

• Enter, run, and modify the example program in chapter 8. 


To Learn Program Planning 

• Read through chapter 8 and experiment with the program devel¬ 
oped there. 

• Develop your own programs based on the methods presented in 
chapter 8. 

• Restructure someone else’s program using the methods of 
chapter 8. 

• Read Appendix G, “Hints for Program Efficiency,” at the back of 
the manual. 


Conventions Used in This Manual 

Throughout this manual you’ll encounter the following conventions: 


Warning 

Warning boxes contain vital information about potentially dangerous 
situations in which you can damage or destroy equipment, programs, 
or information. 


Grey boxes contain minor details, tricky points, side comments, helpful 
hints, historical notes, and other information of secondary tmportance. 



Screen boxes represent information as it will 
appear on the computer's display screen. ;C 

Throughout the manual, extensive use has been made of marginal 
notes for key points, definitions, and cross-references. After reading 
a chapter or section, you can use the marginal notes to review what 
you’ve learned or to refer back to a particular point for quick 
reference. 
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New terms being introduced for the first time are set in italics; defini¬ 
tions for most such terms can be found in the marginal notes, the 
Glossary, or both. 

Numbers (such as memory addresses) preceded by a dollar sign, 
such as $3B00, are expressed in hexadecimal; numbers without a 
dollar sign are generally in decimal, unless otherwise stated. 
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Chapter 1 


General Information 


BASIC: Beginner’s All-purpose Symbolic 
Instruction Code 


ANSI: American National Standards 
Institute 


Applesoft BASIC is a very extended version (in computer parlance, 
a superset) of the BASIC programming language. It includes many 
more features than either the original BASIC, developed at Dart¬ 
mouth College in the 1960s, or the standard version of the language, 
as defined by the American National Standards Institute (ANSI). The 
extra features allow your programs to use the special capabilities of 
the Apple lie, such as color graphics, animation, and hand controls. 


This first chapter introduces the Applesoft language and the environ¬ 
ment in which it operates. Here you will find information on how to 
create, modify, execute, and store Applesoft programs. 


creating and modifying programs: see 

Section 1.1 


operations on whole programs: see 

Section 1.2 


Section 1.1, “Statements and Lines,” deals with the fundamental 
units of Applesoft programs. It tells how to type Applesoft statements 
for immediate execution and how to create and modify programs in 
the computer’s memory. 

Section 1.2, “Operations on Whole Programs,” introduces Apple¬ 
soft’s commands for displaying a program on the screen, writing it to 
an output device such as a printer, executing it, saving it on a disk, 
and retrieving it from a disk. 


interrupting and resuming: see Sec- Section 1.3, “Interrupting and Resuming a Program,” tells how to 
•'ofi 1 -3 suspend or cancel the execution of a running program and how to re¬ 

sume execution after an interruption. 


on-screen editing: see Section 1 .4 Section 1.4, “Editing What You Type,” briefly describes Applesoft’s 

facilities for correcting typing errors and editing text on the screen. 


1.1 

program iine: the basic unit of an Apple¬ 
soft program 

statement: a unit of a program specify¬ 
ing an action for the computer to perform 


Statements and Lines 

The basic unit of an Applesoft program is the program line, which 
may contain one or more statements specifying actions you want the 
computer to perform. Most Applesoft statements are identified by 
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deferred execution: see Section 1.1.2 

one or more keywords, special words that Applesoft recognizes as 
denoting a particular type of statement. 

You can type a program line whenever you see Applesoft’s prompt 
character, a right bracket (]), displayed on the screen followed by 
the cursor. Each line you type must end in a press of the | return | 
key (but see Section 1.1.4 about multiple statements per line). De¬ 
pending on what you type, the statements in the line may either be 
executed immediately or deferred for later execution as part of a 
complete program. 

Use I CAPS LOCK I while typing Apple- 
soft programs 

Applesoft understands only uppercase letters. Most programmers 
therefore keep the | caps lock | key down while typing programs. 

80-Column Text Card: see Apple He 
Owner’s Manual, Apple He 80-Column 

Text Card Manual 

Notice that a program line is not the same thing as a line of text on the 
screen. If the cursor reaches the end of a screen line while you’re typ¬ 
ing a program line, it will “wrap around” to the beginning of the next 
screen line and continue displaying what you type. Although the 
screen is only 40 columns wide (or 80 if you’re using the Apple lie 80- 
Column Text Card), a program line may be up to 239 characters long 
and ends only when you press the I return | key. 

Program lines may be up to 239 charac¬ 
ters long 

Actually, you can type as many as 255 characters In a program line, but 
all characters after 239 will be ignored. If you type more than 255 char-^ 
acters, Applesoft will display a backslash character (\) and cancel the 
entire line. It will then redisplay the prompt character ( 1) followed by the 
cursor, and you will have to retype the entire line from the beginning. As 
a warning, Applesoft will “beep” the computers built-in speaker with 
every character you type beginning with the 245th in a line. 

It’s usually a bad idea to type program lines this long. In practice, you 
should keep your lines well below 239 characters in length. 

1.1.1 

Immediate Execution 

If you want Applesoft to execute a program line as soon as you type 
it, just type the line and press the | return | key. For example, if you 
type 

PRINT statement: see Section 5.2.2 

PRINT "HELLO" 

Applesoft immediately displays the word H E L L 0 on the screen, on 
the line following what you just typed. 


4 


General Information 

























1 . 1.2 


line number: a number identifying a line 
in an Applesoft program 

Maximum line number is 6 3 9 9 9 

program: a sequence of program lines, 
each with a different line number 

1 . 1.3 

Program lines automatically sorted into 
proper sequential order 

Leave intervals between line numbers 

1 . 1.4 

Colons separate multiple statements 


Line Numbers and Deferred Execution 

If you want Applesoft to save a program line to be executed later— 
that is, if you want it to defer execution—then precede the line with a 
line number: 

10 PRINT "HELLO" —10 is the line number 

Line numbers must be in the range 0 through G3393. Applesoft 
uses the presence or absence of line numbers to determine whether 
the line you type is to be carried out immediately or deferred (stored 
for execution at some future time). 

A sequence of deferred-execution lines, each preceded by a differ¬ 
ent line number, is an Applesoft program. Program lines are stored in 
the computer’s memory in sequential order, from the lowest-num¬ 
bered line to the highest. 


Adding Lines to a Program 

To add a new line to a program, just type the new line preceded by a 
line number indicating where in the program you wish to insert it. It 
makes no difference in what order you enter program lines; Applesoft 
will put them in the proper sequential order for you. 

Helpful Hint: Instead of using consecutive line numbers (0, 1,2,...), 
it’s usually more convenient to leave intervals of 5 or 10 or 20 between 
the line numbers in your program. This makes it easy to insert new lines, 
if necessary, in between the old ones. 


Muitipie Statements on the Same Line 

Applesoft allows you to put more than one statement on the same 
program line. Use a colon (:) to separate the statements: 

aO PRINT "COME OUTSIDE" : PRINT "AND 
PLAY" 

You can type as many statements as will fit within the limit of 239 
characters per line. 


Line Numbers and Deferred Execution 
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Multiple statements make editing more 
difficult (although they speed up program 
execution) 


1 . 1.5 


DEL deletes lines from the program in 
memory 


Deleting a single line 


Although using multiple statements on the same line can speed up the 
execution of your program, it can also make program editing difficult and 
time-consuming. The example above, for instance, has two statements 
on the same line. In order to change the word 0 U T SID E in the first 
statement to I NS IDE, you would have to retype both statements. But 
if each statement were on its own line, you would have to retype only 
the one statement you want to change. This may not seem like much 
of a time saving; but when you multiply three or four seconds by the 
hundreds of edits you might need to make in developing a typical pro¬ 
gram, the savings can become considerable. 


Deleting Lines from a Program: 
The DEL Command 

DEL 100» 200 


The DEL command deletes (removes) a range of consecutive lines 
from the program currently in memory. The line numbers of the first 
and last lines to be deleted follow the keyword DEL and are sepa¬ 
rated from each other by a comma. All program lines between the two 
specified line numbers, inclusive, are deleted from the program. The 
example above, for instance, will delete all lines from 10 0 to 200, 
inclusive. 

If either line number is out of the range of lines in the actual program 
(for instance, if the command is D E L 10 0 t 2 0 0 and the highest 
existing line number is 150), then all existing lines within the speci¬ 
fied range are deleted. If D E L specifies a range of lines that doesn’t 
exist, or if the second line number is smaller than the first, the com¬ 
mand has no effect: 

DEL 200 » 100 —nothing happens 

A single number with a comma also has no effect: 

DEL 35 > —nadapasa 

A single number without a comma is a syntax error: 

DEL 35 —syntax error 

To delete a single line from the program, simply type the number of 
that line and press | return | : 

150 —press the | return | key after 

you type the line number 
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If you’re fond of redundancy, you can also use DEL 15 0 # i 5 0 to 
do the same thing. 


Dash not allowed in DEL command 

Unlike the LIS T command, you cannot use a dash (-) to separate the 

line numbers in the D E L command: * 

LIST command: see Section 1.2.3 

DEL BO - iOO —causes a syntax error 


The DEL command is normally used in immediate execution. You can 

also use it from within a program, but as soon as it is executed the pro- ’ 

gram will stop with no error message: 

20 DEL 135t 250 —lines 135 through 250 re¬ 

moved from program; program 
execution halts 


1.1.6 Changing Lines in a Program 



To alter or replace an existing line of your program, simply type the 
new line using the same line number as the existing one. What you 
type will replace the old line under the same line number; the old line 
will be forgotten. 

1.1.7 

Annotating a Program: The REH Statement 

REH TEST FOR ERROR 

R E M is for including explanatory 
remarks to a human reader 

One rule of good programming practice is to include comments in 
your program, explaining or clarifying to a human reader how the pro¬ 
gram works. Applesoft’s REM statement allows you to include such 
remarks within the body of your program. It consists of the keyword 

REM (for “remark”) followed by any explanatory notes you care to in¬ 
clude. For example, 

0 REM MONTHLY BUDGET PROGRAM 


Line Numbers and Deferred Execution 
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LIST command: see Section 1 .g.3 
RUN command: see Section 1.2.4 


This statement is included in the program strictly for the benefit of the 
human reader. When you list the program, the REM statement will 
appear just like any other statement. But when you run the program, 
Applesoft will ignore the R EM statement and just go on to the next 
line. Everything following the keyword R E M on the same line will be 
ignored. See Chapter 8, “Bringing It All Together,” for some tips on 
the use of the R E M statement. 


Operations on Whole Programs 

This section describes Applesoft’s commands for manipulating 
whole programs: 


NEW command: see Section 1.2.1 

CLEAR command.'see Section 1.2.2 

LIST command: see Section 1.2.3 

RUN command: see Section 1.2.4 

SAME command: see Section 1.2.5 

LOAD command: see Section 1.2.6 


• NEW clears the current program from the computer’s memory so 
you can start typing another. 

• CLEAR resets all variables and internal control information to 
their initial settings without affecting the Applesoft program in 
memory. 

• LIST displays the current program on the screen or writes it to 
an output device such as a printer. 

• RUN executes the program currently in memory. It can also be 
used to load and execute a program stored on a disk. 

• SAME writes the program currently in memory onto a disk or a 
tape cassette for future use. 

• LOAD reads a program into memory from a disk or a tape cas¬ 
sette for execution. 


You can use all of these commands for immediate execution; you can 
use some of them from within your Applesoft programs as well. 
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1 . 2.1 


NEW clears memory for a new program 


variables: see Section 2.1 


N E W in deferred execution 


hang: for a program to “spin its wheels” 
indefinitely, performing no useful work 


1.2.2 


null string: a string containing no 
characters 


C L E A R in deferred execution 




The NEW Command 

NEW 


The NEW command clears the current program from memory, resets 
the values of all numeric variables to 0 and those of all string vari¬ 
ables to the null string, and prepares Applesoft to accept a new pro¬ 
gram. If there are no program and no variables in memory, NEW has 
no effect. 

Although NEW is usually used in immediate execution, you can also 
use it in deferred execution (from within a program): 

100 IF A$ = "RATS" THEN NEW 

—NEW in conditional statement 

039 NEW —NEW on its own line 


Warning 

Using NEW in deferred execution can do strange and unpredictable 
things to Applesoft’s innards, causing subsequently entered programs 
to hang. If you use NEW from within a program, it’s a good idea to warn 
your user to restart the system before typing another program: 

too IF A$ = "RATS" THEN PRINT 

"PLEASE RESTART YOUR SYSTEM 
BEFORE TYPING A NEW PROGRAM."; NEW 


The CLEAR Command 

CLEAR 


The CLEAR command resets the values of all numeric variables to 0 
and those of all string variables to the null string; it also resets Apple¬ 
soft’s internal control information to its initial state. It has no effect on 
the program lines in memory. 

Although CLEAR is usually used in immediate execution, you can 
also use it in deferred execution (from within a program): 

100 IF Z$ = "NUTS" THEN CLEAR 

—CLEAR in conditional 
statement 

900 CLEAR —CLEAR on its own line 


Operations On Whole Programs 
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subroutines, control stack; see 

Section 3.4 

F 0 R/N E X T loops: see Section 3.3 


Warning 

Be careful where you execute CLEAR. Since CLEAR resets Apple¬ 
soft’s internal control stack, using it in the midst of a subroutine or in a 
FOR/NEXT loop can Interfere with the orderly flow of program execu¬ 
tion. The following program, for example, will fail in line 30 with a NEXT 
WITHOUT FOR error: 


10 

20 

FOR X = 1 TO 10 

PRINT X 

—try to loop 10 times 

30 

CLEAR 

—CLEAR resets control stack 
(among other things) 

ao 

NEXT X 

—program fails here—doesn’t 
know it’s in a loop 

50 

PRINT "HI I" 

—program won’t get this far 


LIST Command 


1.2.3 The 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 

LIST 


100 
100 » 

- 200 
»200 

100 » 200 
100 - 200 


LIST displays or prints a program The LIST command displays on the screen all or part of the pro¬ 

gram currently in memory, or writes it to the current output device as 
PR# statement: see Section 5.2.1 specified in the last PR# Statement. (For example, if there is a printer 

connected to slot 1, and if the statement PR# 1 has been executed, 
then the program listing is sent to the printer.) 

Listing the entire program To list the entire program, just type the keyword LIST and press 

I RETURN | : 

LIST 

Listing a portion of the program You can list a portion Of the program by specifying the first and last 

lines you want to list, separated by either a comma or a dash: 

LIST 10 0 » 250 —display lines 10 0 through 

250 

LIST 100 - 250 —also display lines 100 

through 250 
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LI ST in deferred execution 


If none of the lines in the specified range are in memory, nothing wiil 
be listed; if the specified range is greater than the actuai range of 
lines in the program, Applesoft will list the entire program. 

If you specify only one line number preceded by a comma or dash, all 
lines from the beginning of the program through the specified line will 
be listed: 

LIST >100 —display from beginning of pro¬ 

gram through line 100 

If you specify only one line number followed by a comma or dash, all 
lines from the specified line through the end of the program will be 
listed: 

LIST 100 - —display from line 10 0 through 

end of program 

If you just specify a single line number, only that line will be listed: 
LIST 100 —display line 10 0 only 

You cannot list line number 0 by itself. You’ll have to use a form like 
LIST ,1 


Warning 

Always be sure to type the keyword LIST before the number of the pro¬ 
gram line you want to list; typing a line number not preceded by a key¬ 
word deletes the specified line from the program (see Section 1.1.5, 
“Deleting Lines from a Program: The DEL Command”). 


Although the LI ST command is usually used in immediate execu¬ 
tion, you can also use it from within a program: 

150 LIST —list entire program 

235 IF Z = K THEN LIST 10»75 

—list lines 10 through 75 if vari¬ 
able Z holds same value as 
variable X 

LIST statements within a program can be particularly useful in debug¬ 
ging. With them, you can test for various error conditions and display or 
print only the section of the program in which the error occurred. 


Operations On Whole Programs 
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1.2.4 The RUH Command 

RUN 

RUN 275 

RUN MONTHLY BUDGET 

RUN executes a program 

The RUN command instructs Applesoft to execute the program 
currently in memory. If no line number is given, execution begins at 
the beginning of the program; if the RUN command includes a line 
number, execution begins at the specified line: 

RUN —execute prog ram from 

beginning 

RUN 500 —execute program from line 

500 

If you attempt to run a program from a specified line number (as in R U N 

500) and that line doesn’t exist, the message 

?UNDEF'D STATEMENT ERROR 

will be displayed and program execution will halt. 

RUN in deferred execution 

Although RUN is normally used in immediate execution, you can also 
use it from within a program: 

150 IF A = 0 THEN RUN 

—if value of A is 0, then execute 
program from beginning 

235 RUN BOO —execute program from line 

BOO 

You can use this technique, for example, to restart a game or to avoid 
executing some code with low line numbers. 

variables: see Section 2.1 

Warning 

Whenever the R U N statement is executed, it resets the values of all nu¬ 
meric variables to 0 and those of all string variables to the null string be¬ 
fore executing the first program line. If you have assigned values to any 
variables in immediate execution, those values will be forgotten. This 
happens even if there is no program currently in memory. 

Running a program from a disk 

If your computer is equipped with a disk drive and the Disk Operating 
System (DOS) is active, you can use the R U N command to load a 
program into memory from a disk file and execute it. To do this, follow 
the keyword RUN with the file name under which the program is 
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1 . 2.5 


S A E writes a program to a disk or 
tape 


Saving programs on tape: see Appen¬ 
dix M 


I CONTROL | - |reset| : see Section 1.3.2 


Stored on the disk. For example, if the program you want to run is 
stored in a file named AWAY, first make sure the disk containing that 
file is in the disk drive, then type 

RUN AWAY 

and press | return | . Applesoft (and DOS) will do the rest. 

If you try to use this form of the R U N command with no disk drive con¬ 
nected to your computer, or without DOS loaded and active, you’ll get a 
syntax error. 


For nfiore Information on disk drives, disks, files, and file names, see 
the DOS manual that came with your disk drive. For related Applesoft 
commands, see Sections 1.2.5, “The SAME Command,” and 1.2.6, 
“The LOAD Command.” For Information on using a cassette tape re¬ 
corder in place of a disk drive, see Appendix M, “If You Have a Cassette 
Recorder.” 


The SAME Command 

SAUE 

SAUE MONTHLY BUDGET 


On systems equipped with a disk drive, the SAME command writes 
the Applesoft program currently in memory to a file on a disk. The 
keyword SAME is followed by the file name under which the program 
is to be written. The copy of the program in memory is not affected in 
any way. For example, 

SAME MY CHILD —store current program on disk 

under file name MY CHILD 

Attempting to use this form of the SAME command with no disk drive 
connected to your computer, or without the Disk Operating System 
(DOS) loaded and active, will result in a syntax error. 


If you issue the S A M E command without specifying a file name, Apple¬ 
soft will attempt to write the program in memory onto a tape cassette. If 
no cassette recorder is connected, the computer will seem to hang for a 
while; the actual time that will pass before you regain control depends on 
the length of the program in memory. You can regain control immediately 
by pressing | control | - |reset| . 


Operations On Whole Programs 
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1 . 2.6 


LOAD reads a program from a disk 
or tape 


RUN command: see Section 1.2.4 


Loading programs from tape: see 

Appendix M 


' I CONTROL | - | RESET | : See Section 1.3.2 


For more information on disk drives, disks, files, and file names, see 
the DOS manual that came with your disk drive. For related Applesoft 
commands, see Sections 1.2.4, “The RUN Command,”and 1.2.6, “The 
LOAD Command.” For Information on using a cassette tape recorder in 
place of a disk drive, see Appendix M, “If You Have a Cassette 
Recorder.” 


The LOAD Command 

LOAD 

LOAD MONTHLY BUDGET 


On systems equipped with a disk drive, the L 0 A D command reads 
an Applesoft program from a file on a disk into the computer’s mem¬ 
ory for execution or editing. The keyword L 0 A D is followed by the file 
name under which the program is to be found on the disk. For 
example, 

LOAD THE DICE —load program into memory 

from file named THE DICE 

LOAD does not execute the program it retrieves; it merely reads a 
copy of the program into memory. You can then execute the program, 
if you wish, with the R U N command. The copy of the program on the 
disk is not affected in any way. 

If the disk in the disk drive doesn’t contain a file of the specified name, 
the error message 

FILE NOT FOUND 

will be displayed. If there is no disk drive connected to your computer, or 
if the Disk Operating System (DOS) isn’t loaded and active, you’ll get a 
syntax error. 


If you issue the L 0 A D command without specifying a file name, Apple¬ 
soft will attempt to read a program into memory from a tape cassette. If 
no cassette recorder is connected, or if the tape in the recorder doesn’t 
contain a program to load, or if the recorder is turned off, the computer 
will hang forever looking for a pr ogram tha t isn’t there. When you get 
bored waiting, press | control ] - | reset | to regain control. 
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For more information on disk drives, disks, files, and file names, see the 
DOS manual that came with your disk drive. For related Applesoft com¬ 
mands, see Sections 1.2.4, “The RUN Command,” and 1.2.5, “The 
SAVE Command.” For information on using a cassette tape recorder in 
place of a disk drive, see Appendix M, “If You Have a Cassette 
Recorder.” 


Interrupting and Resuming a Program 

If a program starts to run away from you, there are various ways of 
interrupting it and regaining control. This section covers Applesoft’s 
facilities for getting out of problem programming situations, infinite 
loops, and the like. 


1 .3.1 Suspending Screen Output 

Quite often the output a program displays, or the listing of the pro¬ 
gram itself, exceeds the number of lines available on the display 
screen, causing the output to fly by on the screen too fast for you to 
read. In such cases, you can press | control | -5 (type the letter S 
while holding down the | control | key) to suspend the output of text 
to the screen temporarily so that you can comfortably read what’s 
there. I cqntrqlI -S doesn’t permanently discontinue the display of 
text; pressing any key, including another | control | -S, causes 
screen output to resume. You can then suspend it again with another 
I CONTROL l -S.To discontinue a program or a listing permanently, use 

I CONTROL | -C. 

Helpful Hint: E xperienced programmers looking at listings of long pro¬ 
grams keep the I control | key continually pressed; they control the list¬ 
ing by pressing the S key whenever they want to suspend or continue it. 


1 .3.2 Interrupting Program Execution 

Applesoft gives you two ways of interrupting the execution of a run¬ 
ning program or canceling a listing. Pressing | control | -C interrupts 
the program in such a way that it is usually possible to resume execu¬ 
tion from the point of the interruption; | control | - | reset I is some¬ 
what more drastic, and often leaves the system in a state from which 
the program can’t be resumed with a CONT statement. 


I CONTROL 1 -S temporarily suspends 
screen output 


I CONTROL l -C: see Section 1.3.2 


Interrupting and Resuming a Program 
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I control1 -C 

I CONTROL l -c cancels execution or Pressing | CONTROL | -C (typing the letter C while holding down the 
listing of a program | CONTROL | key) cancels the execution or listing of a program and re¬ 

turns Applesoft to its command level, displaying the prompt character 
(]). You can then resume execution of the program, if you wish, with 
the C 0 N T command. To cancel execution of a program that is wait- 
IN PUT statement: see Section 5. 1.2 ing for a response to an INPUT statement, | control | -C mustbe 

the first character typed and must be followed immediately by 

I RETURN I . 


GET statement: see Section 5.1.3 


ASCII code: see Section 4.2.1 and 
Appendix C 


250 GET A$ —wait for user to press a key 

260 IF A$ = CHR$(3) THEN STOP 

—if user presses | control | -C 
(ASCII code 3), then stop 


Interrupting a G E T: | control | -C will not interrupt a program waiting 
for a response to a GET sta tement; unlike the IN PUT statement, GET 
will assume that | control hC is a valid r esponse and will assign the 
ASCII code for the character | control | -C to the specified variable. 

To allow a p rogram halted at a G E T statement to be Interrupted with 
I CONTROL I -C, use this form: 


Warning 


In certain situations, using | control | -C can disconnect the disk operat¬ 
ing system. See the DOS manual for information on this point. 


I CONTROL l - fPESET | 

In most cases you can immediately and unconditionally stop the 
execution of any Applesoft program or command by pressing 
I CONTROL l - l RESET | unconditionally | CONTROL hi RESET" I (pressing the I RESET~| key while holding down 
stops any program or command | CONTROL | key). The program in memory remains intact, but 

some of Applesoft’s internal “housekeeping” information is changed; 
as a result, it may not be possible to resume execution of the program 
with theCONT command. 

Controlling | control | - 1 reset! : Your Apple lie has an advanced soft¬ 
ware featur e called a r e set vec tor, which allows you to control what hap¬ 
pens when I CONTROL j - |reset| is pressed. You can use the reset vector 
to make the program continue as if nothing had happened, branch to 
some other portion of the program, or do whatever you choose. Use of 
Apple lie Monitor program: see Apple this technique requires knowledge of the Apple He’s built-in Monitor pro- 

lle Reference Manual gram: see the Apple lie Reference Manual for details. 
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1 . 3.3 


CONI continues execution after an 
interruption 

STOP statement: see Section 3.6.1 
END statement: see Section 3.6.2 
I CONTROL | -C: see Section 1.3.2 

When CONT won’t work 

INPUT statement: see Section 5.1.2 


A 


1.4 

Tutorials abound... 


Resuming Program Execution: 
The CONT Command 

CONT 


The CONT (for “continue”) command is used to resume execution of 
a program after it has been interrupted byaSTOPorEND statement 
or by pressing | control | -C. Execution wiii continue at the first state¬ 
ment after the S T 0 P or E N D, or at the point in the program where 
execution was interrupted by | control | -C. 

CONT won’t work if 

• the program has been stopped because of an error 

• an error has occurred in immediate execution 

• an IN P U T statement has been interrupted with | control | -C 

• any program line has been edited since the program stopped 
running 

However, you can continue the program with CONT after examining 
or changing the vaiues of variabies, provided you haven’t edited any 
program lines. 

When a program is interrupted with | control | - | reset [ , CONT may or 
may not be able to continue execution. Let the programmer beware! 


Warning 

The CONT command should be used in immediate execution only. If it is 
executed from within a program, it will cause the program to hang. 


Editing What You Type 

This section gives a very brief description of Applesoft’s facilities for 
correcting typing mistakes and editing text on the screen. More de¬ 
tailed discussions of these features can be found in the Apple He 
Owner’s Manual and the Appie lie Applesoft Tutorial. For hands-on 
experience with the various keys and editing features, use the 
APPLE PRESENTS... APPLE training disk. 


Editing What You Type 
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1 .4.1 Canceling an Input Line 


I CONTROL l -x cancels a line of input | CONTROL | -K is your “escape hatch.” By typing the letter K while 

holding down the I control! key, you can change your mind (as long 
as you haven’t yet pressed the | return | key) and cancel a program 
line that you’re entering or editing or a line of input that you’re in the 
midst of typing to a program. Applesoft will display a backslash (\) at 
the end of the line you were typing, to show that it’s ignoring that in¬ 
put, and will redisplay the cursor at the beginning of the next line of 
the screen. 

• If you were typing a new program line, the whole line is elimi¬ 
nated and you can start over again. 

• If you were retyping a previously entered program line, any 
changes you had typed will be canceled. 

• If you were typing input to a running program, the line you were 
typing is ignored and the program waits for your new response. 

I CONTROL I -X does not affect any previous input you’ve typed or pro¬ 
gram lines already entered. 


1 .4.2 The Arrow Keys 

There are four arrow keys on the Apple lie keyboard: 

• The I LEFT-ftRROM | key works as a backspace. It moves the cur¬ 
sor one position to the left and “erases” the last character typed 
from the keyboard (or recopied with the | right-arrou | key; see 
below). No characters are removed from the screen, but the last 
character typed is forgotten, as if it had never been typed. 

• The I RIGHT-ARROW | key “recopies” the character under the cur¬ 
sor as if it had been typed from the keyboard, then moves the 
cursor one position to the right. Moving the cursor over a charac¬ 
ter with I RiGHT-ARROM | is exactly the same as typing that char¬ 
acter from the keyboard. 

• The I DOHN-ARRow| moves the cursor down one line without eras¬ 
ing or recopying any characters. 

• The I up-arroh 1 key has no effect in Applesoft. 

Notice that the |left-arrqm 1 key doesn’t erase any characters from the 
screen; it just tells Applesoft to “forget” the last character it received. If 
pure cursor moves: see Section 1.4.3 any pure cursor moves have been used, the character “erased” may not 

even be the one the cursor backs up over. 


18 


General Information 









































escape mode: see Section 1.4.3 In escape mode, all four arrow keys function as pure cursor moves, 

equivalent to I (up), J (left), K (right), and M (down). That is, they 
lose their backspace and recopy functions and simply move the cur¬ 
sor one position in the indicated direction, remaining in escape 
mode. To cancel escape mode after moving the cursor, press the 
I SPACE | bar. 


The Apple lie keyboard’s auto-repeat feature Is particularly handy for 
long cursor moves. If you press and hold down any of the arrow keys, the 
INPUT statement: see Section 5.1.2 cursor will move repeatedly in the indicated direction for as long as you 

hold down the key. (Exception: the j up - arro w | key doesn’t move the 
GET statement: see Section 5.1.3 cursor unless you’re in escape modeT) 


ASCII: see Section 4.2.1 and Appendix C 


Table 1-1 ASCII Equivalents of Arrow 
Keys 


Key 

ASCII 

Code 

Keyboard 

Equivalent 

I LEFT-ARROW | 

8 I 

CONTROL |-H 




I RIGHT-ARROW 

I 21 1 

CONTROL l-U 




I UP-ARROW I 

1 

CONTROL |-K 


For Experts Only: The | up-arrqw I and | down-arrow | keys can be 
typed by the user in response to an I N PU T stateme nt in a running Ap¬ 
plesoft program. ( | left-arrow | and Iright-arrow ! can’t be, because 
they’re interpreted as backspace and recopy, even in program input; but 
any of the four arrow keys can be typed as a response to a G E T state¬ 
ment.) In your own programs, you can make the arrow keys mean just 
what you choose them to mean (neither more nor less) by having the 
program test the input for each arrow’s ASCII value, as shown in Table 1 - 
1. The program can then take any action you want on receiving one of 
these codes from the user. 

(“The question is,” said Alice, “whether you can make keys mean so 
many different things.” 


I dqwn-arrW| 


10 I CONTROL | -J 


“The question is,” said Humpty Dumpty, “which is to be master—that’s 
all.”) 


1.4.3 Escape Mode 


|es^ alters meanings of some keys Pressing the |Esc | (for “escape”) key puts Applesoft into a state 

called escape mode, in which certain keys take on special mean¬ 
ings. Some of the keys become pure cursor moves, meaning that 
they move the cursor around on the screen without erasing or 
recopying characters or affecting Applesoft’s input in any way. Others 
can be used to clear away all text from all or part of the screen, again 
without having any effect on the input received by Applesoft. 


Although Applesoft normally doesn’t understand lowercase letters, it will 
accept them in escape mode. All of the letter keys listed below will have 
the same effect whether they are typed in upper- or lowercase. 
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Figure 1-1 Single Cursor Moves 
A, 5, C, D move cursor one position 


D 



C 


Figure 1-2 Long-range Cursor Moves 

I, J, K, M are for iong-range moves 


I 



M 


Arrows also work for long-range moves 


E, F, @ clear all or part of the screen 


text window: see Section 5.2.4 


In escape mode, the following characters move the cursor one posi¬ 
tion in the stated direction and then leave escape mode. To continue 
moving the cursor, you have to press the | esc | key again. The func¬ 
tions of these keys are illustrated in Figure 1 -1. 

• A moves the cursor one position to the right. 

• B moves the cursor one position to the left. 

• C moves the cursor down one line. 

• D moves the cursor up one line. 

The following characters move the cursor one position in the stated 
direction and remain in escape mode. You can then continue moving 
the cursor without pressing the I esc | key again. These keys are 
especially useful for long-range cursor moves. The functions of these 
keys are illustrated in Figure 1 -2. 

• I moves the cursor up one line. 

• J moves the cursor one position to the left. 

• K moves the cursor one position to the right. 

• M moves the cursor down one line. 

Notice that the I, J, K, and M keys form a diamond shape on the key¬ 
board, representing the directions in which these keys move the cursor 
{I up, J left, K right, M down). 


The four arrow keys function in escape mode exactly the same as I, J, 
K, and M. That is, they move the cursor one position in the indicated di¬ 
rection and remain in escape mode. 


The Apple lie keyboard’s auto-repeat feature is particularly handy for 
long cursor moves. If you press and hold down I, J, K, H, or any of the 
arrow keys while in escape mode, the cursor will move repeatedly in the 
indicated direction for as long as you hold down the key. 

In escape mode, the following keys clear away all text from all or part 

of the display screen and then leave escape mode: 

• E clears from the current cursor position to the end of the line. 

• F clears from the current cursor position to the end of the text 
window. 

• i clears the entire text window and moves the cursor to the top- 
ieft corner. 
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The special functions of all keys in escape mode are summarized in 
Table 1 -2. To leave escape mode, press any key except one of those 
listed in the table. 


Leaving escape mode 


Table 1-2 Escape-Mode Functions 


To avoid inadvertently p ressing a key that has a special meaning, it’s 
safest always to use the | space | bar to leave escape mode. 


Key 


Function 


A 

Moves cursor 

B 

Moves cursor 

C 

Moves cursor 

D 

Moves cursor 

I 

Moves cursor 

J 

Moves cursor 

K 

Moves cursor 

M 

Moves cursor 

I LEFT-ARROW | 

Moves cursor 

I RIGHT-ARROW | 

Moves cursor 

I UP-ARROW I 

Moves cursor 

I DOWN-ARROW | 

Moves cursor 


right one position; leaves escape mode 
left one position; leaves escape mode 
down one line; leaves escape mode 
up one line; leaves escape mode 

up one line; remains in escape mode 
left one position; remains in escape mode 
right one position; remains in escape mode 
down one line; remains in escape mode 

left one position; remains in escape mode 
right one position; remains in escape mode 
up one line; remains in escape mode 
down one line; remains in escape mode 


E Clears from cursor to end of line; leaves escape mode 

F Clears from cursor to end of text window; leaves escape mode 

@ Clears entire text window; moves cursor to top-left corner; leaves 

escape mode 
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The EXP Function 
The LOG Function 

2.4.2 Generating Random Numbers: The RND Function 

2.4.3 Defining Your Own Functions: The D E F F N 
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Chapter 2 


variables: see Section 2.1 

assignment statement: see Section 2.2 

expressions, precedence rules: see 
Section 2.3 

functions: see Section 2.4 


2.1 

variable: a symbol representing a loca¬ 
tion in the computer’s memory where a 
value can be stored 


Variable types 

real variables: see Section 2.1.2 


Variables and Arithmetic 


This chapter deals with variables and arithmetic in Applesoft. These 
concepts are fundamental to Applesoft programming and will appear 
again and again throughout this manual. 

Section 2.1, “Variables,” discusses how to define and use variables, 
the various types of variable available in Applesoft, and the rules for 
naming them. 

Section 2.2, “Assigning Values to Variables: The Assignment State¬ 
ment,” deals with one of Applesoft’s most basic types of statement, 
the assignment statement. 

Section 2.3, “Expressions,” discusses arithmetic operators and 
expressions and the rules of precedence that govern them. 

Section 2.4, “Functions,” covers Applesoft’s built-in arithmetic func¬ 
tions and tells how you can define your own functions. 

Variables 

A variable is a symbol representing a location in the computer’s 
memory where a value can be stored. The first time your program as¬ 
signs a value to a particular variable, Applesoft automatically allo¬ 
cates a memory location or locations for that variable and stores the 
specified value at that location. Thereafter, whenever your program 
uses that particular variable name, Applesoft will take the name to 
refer to the value stored at the corresponding location. For instance, 
if the variable PI refers to a memory location where the value 
3.14159 is stored, then the statement PR I NT PI will display 
the value 3 4 14159 on the screen. 

Applesoft has three types of variable: 

• Real variables can contain either whole numbers or numbers 
containing decimal fractions. 
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integer variables: see Section 2.1.3 
string variables: see Section 2.1.4 

arrays: see Section 2.1.5 

Reals save time; integers save space 

subroutines: see Section 3.4 
loops: see Section 3.3 


2.1.1 

Rules for variable names 


Table 2-1 Variable Types 


• Integer variables can contain whole numbers only. 

• String variables can contain strings of text characters such as 
words or names. 

In addition, Applesoft allows you to define collections of variables, 
called arrays, of any of the types listed above. 

Programming Tip: Applesoft converts all integer values to real form be¬ 
fore performing arithmetic on them. Because this conversion takes time, 
integer arithmetic is considerably slower than arithmetic on real quan¬ 
tities. However, integers take up less space in the computer’s memory 
than real numbers. In relatively small programs in which space is not a 
concern, you can speed up your program by using real variables instead 
of integers wherever possible, especially in subroutines, loops, and 
other sections of code that are executed many times. In large programs 
where space is critical, you can save space at the expense of time by 
using integers instead of reals, particularly in arrays containing many 
elements. See Appendix G, “Hints for Program Efficiency,” for further 
suggestions on how to save space and time in your programs. 


Variable Names 

The name of a variable must begin with a letter of the alphabet, which 
may be followed by one or more letters and/or digits. In addition, the 
names of all integer variables must end with a percentcharacter ('!) 
and those of string variables must end with a dollar sign ($). The var¬ 
ious variable types and the rules for naming them are summarized in 
Table 2-1. 


Simple Array 


Type 

Symbol 

Examples 

Examples 

Real 

(none) 

K 

AGE (CHILD) 



PRICE 

TAX (ITEM) 



N1 

N1 iJlt 3) 

Integer 

1 

J1 

YEAR‘;i: (N) 



Q51 

B00K% (COUNT) 



Hll 

Nn. iJlt 3) 

String 

$ 

A$ 

SHOP$ (5) 



SAM$ 

DAY$ (NEEK) 



Nl$ 

Nl$ iJlt 3) 
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A variable name can be up to 239 characters long, but Applesoft uses 
only the first two characters to distinguish one variable from another 
of the same type. All characters beyond the first two in a name are ig¬ 
nored, so long as they don’t include a reserved word (see below). 

Don’t begin variable names of the same 
type with the same first two characters 

Take care not to begin the names of different variables of the same type 
with the same two characters. Applesoft will consider the names SUM 
and SUNSTROKE, for example, to refer to the same variable, since 
they both begin with the same two characters. 

Notice that the restriction above applies only to variables of the same 
type. The names T AX, T AXX, and T A K$ refer to three different 
variables, even though they all begin with the same two characters, be¬ 
cause they are of different types (real, integer, and string). However, 
names of the same type that begin with the same two characters—such 
as TAM and TAMABLE, IHlSt and THIHI or OTTER$ 
and 0 T H E R f—refer to the same variable. 

Reserved words illegal in variable 
names 

Reserved Words: Certain words used in Applesoft are reserved for 
special uses in specific commands; you can’t use these words as vari¬ 
able names or as parts of variable names (even beyond the first two 
characters). For instance, TOTAL or SUBTOTAL would be illegal as 
variable names, because they both contain the reserved word T 0. See 

Appendix D, “Reserved Words,” for a list of Applesoft’s reserved words. 

2.1.2 

Real Variables 

Range of real values 

A real variable can hold any numeric value, with or without a 
decimal point, between - 3.93939933E-t-37 and 
+ 9.99999933E -I- 37 (where “E -1-37” means “times 10 
to the -h 37th power”). Applesoft represents real numbers to 

32 bits (about 9 digits) of precision. 

Real variable names consist of letters 
and digits only 

The name of a real variable must consist of letters and digits only. 

Some legal real variable names are 

SAM 

TAX 

Q7 

SUMOFALLNUMBERS 

Real variables preset to 0 

Until they are given some other value with an assignment statement, 
all real variables are preset to the value 0. 

2.1.3 

Integer Variables 

Integer variables can hold only whole-number values between 
- 3 2 7 B 7 and -1- 3 2 7 G 7. The name of an integer variable must 
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Integer variable names end with % 


Integer variables preset to 0 


Real values assigned to integer variables 

are truncated, not rounded 


2.1.4 

string: a sequence of text characters; 
see Section 4.2 


String constants enclosed in double 
quotation marks 


null string: a string containing no 
characters 


end with the percent character (1). Some legal integer variable names 
are 

SHAREI 

D51 

TAXI 

Until they are given some other value with an assignment statement, 
all integer variables are preset to the value 0. 

If a number containing a decimal fraction is assigned as the value of 
an integer variable, It Is truncated to the next lowest whole number— 
not rounded to the nearest whole number: 

LET AI = 32.G78 —value 3 2 assigned to variable 

AI 

LET BI = -34.2 —value - 3 5 assigned to vari¬ 

able BI 


String Variables 

A string is a sequence of text characters (letters, digits, and punctua¬ 
tion marks). Just as you can write numeric constants such as 2 7 and 
2.2 3 B in your Applesoft programs, you can write string constants 
by enclosing the characters in the desired string between double 
quotation marks: 

"NOT WITH A BANG BUT A WHIMPER" 

"George Bernard Shaw" 

"H234J7" 

"$?*!!X" 

Even though Applesoft doesn’t understand lowercase letters when you 
use them in keywords, it will allow you to use them in a string constant, 
as the second example above shows. 

A string can contain from 0 to 255 characters; when it contains no 
characters it is called a null string. Two quotation marks with nothing 
between them denote the null string: 

"" —a string with no characters 
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string variable names end with $ 


String variables preset to null string 


2.1.5 

array: a collection of variables referred to 
by the same name and distinguished by 
means of numeric subscripts 


simple variable: a variable that is not an 
element of an array 


Figure 2-1 A Typical Array 


R (0) 
R (1 ) 
R (2) 
R (3) 
R (4) 


Array R 


53 


27*35 


31 *4 


e 
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R(S) 

R (S + 2) 


A string variable can hold any string as its value. Its name must end 
with a dollar sign ($). Some legal string variable names are 

NAME$ 

S9$ 

J$ 

Until they are given some other value with an assignment statement, 
all string variables are preset to the null string. 


Arrays: Collections of Variables 

An array is a collection of variables referred to by the same name, 
usually holding a collection of data items that are related to each 
other in some logical or systematic way. The individual variables in 
the array are called its elements, and are distinguished from one an¬ 
other by means of identifying index numbers called subscripts. 

An array can be of any type: integer, real, or string. Array names fol¬ 
low the same rules as simple variable names of the same type. To re¬ 
fer to a particular element of an array, write the array name followed 
by one or more subscripts, separated by commas and enclosed in 
parentheses. The subscripts refer to the position of the desired ele¬ 
ment within the array: 

0 ( B ) —element G of real array 0 

FIGURED ( N ) —element N of integer array 

FIGURE/f. 

NAME$ (J - 3) —element J - 3 of string ar¬ 

ray NAHE$ 

COUNT (SUH/f.» 2) —eiement (SUM% > 2) of real 

array COUNT 

Figure 2-1 shows a real array named R with five elements, numbered 
0 to 4. Element R ( 0 ) (pronounced “R-sub-zero”) holds the value 
53, R ( 1 ) holds 27.35, and so on. If the value of variable S is 2, 
then the expression R (S) refers to element R ( 2), whose value is 
31.4,andtheexpressionR(S -I- 2) refers to element R ( 4), 
which holds the value 19. 

For a fuller discussion of arrays and their use, see Section 4.1, 
“Arrays.” 
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Assignment statement assigns a new 
value to a variable 


NEW command : see Section 1.2.1 
CLEAR command: see Section 1.2.2 
RUN command : see Section 1.2.4 

Keyword L E T is optional 


Assigning Vaiues to Variabies: The 
Assignment Statement 

LET PI = 3.141502B5 
COUNTX = 0 


Before Applesoft begins executing a program, it sets the values of all 
real and integer variables to 0 and the values of all string variables to 
the null string (that is, a string containing no characters). The pro¬ 
gram can then change the value of any variable at any time by exe¬ 
cuting an assignment statement. 

The NEW,CLEAR, and RUN commands also reset all real and integer 
variables to 0 and all string variables to the null string. 


An assignment statement cons\sts of the optional keyword LET, fol¬ 
lowed by the name of the variable whose value is to be changed, an 
equal sign (=), and an expression denoting the new value to be as¬ 
signed to that variable. The equal sign means “receives the value” or 
“is assigned the value”; it is often read simply as “gets” (“X gets Y 
plus 2”). The assignment statement means “evaiuate the expression 
to the right of the equal sign and assign the resulting value to the vari¬ 
able named to the left of the equal sign.” The variable will then con¬ 
tinue to hold that value until it is changed by another assignment 
statement or is reset by a NEW, CLEAR, or RUN command. For 
example. 


LET 0 = 27*a 
LET D3 = J 

COUNTI = A + B 

S9Z = 35 
NAME$ = "SAM" 


—assign value 27.4 to real 
variable Q 

—assign current value of real 
variable J to real variable 03; 
variable J unchanged 

—assign current value of real 
variable A plus current value 
of real variable B to integer 
variabie C □ U N T 7.; variables A 
and B unchanged 

—assign value 35 to integer 
variable S97. 

—assign string value " S AM" to 
string variable N A ME $ 
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arithmetic operators: see Section 2.3.1 
reiationai operators: see Section 2.3.2 

iogicai operators: see Section 2.3.3 

2.3.1 

Arithmetic operators combine nu¬ 
meric vaiues to produce numeric 
results 


—assign current value of string 
variable S A M $ to string vari¬ 
able NAME$; variable SAM$ 
unchanged 

—assign value 3B to element 5 
of real array BOX 

—assign current value of ele¬ 
ment N of integer array A “L to in¬ 
teger variable JX; array AX and 
variable N unchanged 

SHOP$(N) = "BAKERY" —assignvalue "BAKERY" to 

element N of string array 
SHOP$ 

The keyword L E T is optional in assignment statements. The statements 

LET Q = 27.4 

and 

0 = 27.4 

mean exactly the same thing. 


NAME$ = SAM$ 

B0X(5) = 36 
JX = AX(N) 


Expressions 

An expression is a formula describing a calculation for the computer 
to perform. It may involve any number of numeric variables and con¬ 
stants, together with operators specifying how the values of the vari¬ 
ables and constants are to be combined. There are three kinds of 
operator that can be used in an Applesoft expression: 

• Arithmetic operators combine two numeric values and produce a 
numeric result. 

• Reiationai operators compare two values and produce a logical 
(true-or-false) result. 

• Logical operators combine two logical values and produce a logi¬ 
cal result. 

Table 2-2 summarizes the various operators available in Applesoft. 


Arithmetic Operators 

Arithmetic operators combine two numeric values to produce a nu¬ 
meric result. There are five of them in Applesoft, corresponding to the 
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Table 2-2 Operators 


Arithmetic Operators 


familiar operations of arithmetic: + (addition), - (subtraction),* 
(multiplication), / (division), and " (exponentiation). Here are some 
examples of their use: 


* 

/ 

addition 

subtraction 

multiplication 

division 

exponentiation 

3 + 4 

+ 144 

X + Y 

—3 plus 4, yielding 7 

—plus 144 (a positive number) 

—the value of X plus the value 
ofY 

Relational Operators 

= equal to 

< less than 

> greater than 

< = less than or equal to 

= < 

> = greater than or equal to 

= > 

23.7 - 11.4 

50 - 75 

- 144 

—23.7 minus 11.4, yielding 
12.3 

—50 minus 75,yielding - 25 

—minus 14 4 (a negative 
number) 

<> 

>< 

not equal to 

SUMI - 2 

13 * 5 

—the value of S L) M "L minus 2 

—13 times 5, yielding G 5 

Logical Operators 

B * . 25 

—8 times . 25, yielding 1.5 

AND 

OR 

NOT 

both true 
either or both true 
is false 

25 * OUARTERSX 

—25 times the value of 
QUARTERS! 



4.8 * C0UNT(5) 

—4.8 times the value of ele¬ 
ment 5 of array COUNT 



18 / B 

—18 divided by 8, yielding 3 



B / 18 

—8 divided by 18, yielding 
.333333333 



DIST / TIME 

—the value of D18 T divided by 
the value of TIME 



DOLLARS^. / 100 

—the value of D 0 L L A R 8 ! 
divided by 100 



2 " 3 

—2 to the 3rd power, yielding 8 



3 - .5 

—3 to the .5 power, yielding 


1.73205081 

J “L —the value of X raised to the 

power of the value of JI 


Like most other computer languages, Applesoft uses an asterisk (*) in¬ 
stead of the letter X to represent multiplication. 
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What to Do with Fractions: Applesoft doesn’t treat fractional numbers 
In the way that you are probably used to dealing with them. Most people 
would read the expression 3 3 / 4 as “three and three quarters.” To 
Applesoft, however, the same expression would mean “thirty-three di¬ 
vided by four.” (Applesoft ignores any spaces It finds in a number.) 

It’s easy to convert fractions to a form Applesoft will understand cor¬ 
rectly. Just think of 3 3 / 4 as “three plus three divided by four”. In 
other words, instead of typing 

LET A = 3 3/4 

type this instead: 

LET A = 3 + 3/4 

Applesoft will do the rest. 


2 . 3.2 Relational Operators 

Relational operators compare values A relational operator tests for a relation between two values and pro- 

and produce logical results duces a logical (true-or-false) result, depending on whether the par¬ 

ticular relation does or doesn’t hold between those two values. For 
example, the expression 

A > B 

means “the value of variable A is greater than that of variable B.” If 
the current value of variable A is 5 and that of B is 3, then the relation 
is true: if the value of B is 8, the relation is false. 

Relational operators are particularly useful in connection with the 
IF... T H E N statement, discussed in Section 3.2.2. 


1 stands for true 
0 stands for false 


The Truth about Applesoft: Applesoft actually uses numeric values to 
represent the logical values true and false: if the stated relation is true, 
the value of the relational expression is 1; if the relation is false, the 
value of the expression is 0. For example, if you type the statement 

PRINT B > 12 

in immediate execution, Applesoft will respond by displaying the number 
0, meaning “false”: if you type 

PRINT 12 > B 

Applesoft will display the number 1, meaning “true.” 
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Applesoft has six relational operators (some of which can be written 
in more than one way): = (equal to), < (less than), > (greater than), 
< = or = < (less than or equal to), > = or = > (greater than or 
equal to), and <> or >< (not equal to). Here are some examples of 
their use: 


= means eQL/a/to 


< means less than 


> means greater than 


< = or =< means less than or equal to 


> = or = > means greater than or 
equal to 


B = B 
B = 12 

K = 2 

NAME$ = "Ann" 
B < B 
B < 12 


PROBABILITY < .5 


B > B 


B > 12 


AGE > B5 


B <= B 
B =<''B 

B <= 12 
B =< 12 

AZ <= 3 * BI 
A% =< 3 * BI 

B >= B ‘ 

B => B 

B >= 12 
B => 12 

SALARY >= 20000 
SALARY => 20000 


—B equals B, yielding 1 for true 

—B equals 12, yielding 0 for 
false 

—the value of K is equal to 2 

—the value of N A M E $ is equal 
to the string "Ann " 

—B is less than B, yielding 0 for 
false 

—Bis less than 12, yielding 1 
for true 

—thevalueof PROBABILITY 
is less than • 5 

—B is greater than B, yielding 0 
for false 

—B is greater than 12, yielding 
0 for false 

—the value of A G E is greater 
than B 5 

—B is less than or equal to B, 
yielding 1 for true 

—Bis less than or equal to 12, 
yielding 1 for true 

—the value of A 1 is less than or 
equal to 3 times the value of B 1 

—B is greater than or equal toB, 
yielding 1 for true 

—B is greater than or equal to 
12, yielding 0 for false 

—the value of S A L A R Y is 
greater than or equal to 
20000 
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- ...» 


< > or >< means not equal to 

G <> B 

G >< B 

—G is not equal to G, yielding 0 
for false 


G <> 12 

G >< 12 

—G is not equal to 12, yielding 

1 for true 


> > 

A V 

V A 

X X 

—the value of K is not equal to 
the value of Y 


BANG$ >< "WHIMPER" 
BANG$ <> "WHIMPER" 

—the value of B A N G $ is 
not equal to the string 
"WHIMPER" 

2.3.3 

Logical Operators 


Logical operators combine logical val¬ 
ues to produce logical results 

A logical operator combines two logical (true-or-false) values and 
produces a logical result. There are three logical operators in Apple¬ 
soft: AND, OR, and NOT. Here are some examples of their use: 

AND yields true if both original expres¬ 
sions are true 

0 R yields true if either or both of the 
original expressions are true 

B <= 12 AND G >- 

.25 <= R AND R < < 

G <- 12 OR G >= 1 

12 

—B is less than or equal to 12 
and B is greater than or equal 
to 12; value is 0 for false 

• 75 

—. 2 5 is less than or equal to 
the value of R and the value of 

R is less than . 75 

7 

—G is less than or equal to 12 
or G is greater than or equal to 

12; value is 1 for true 


ANIMAL$ = "DOG" OR 

ANIMAL$ = "CAT" 

—the value of AN I MAL$ is 
equal to the string " D 0 G" or 
the string "CAT" 

NOT yields true if the original expression 
is false 

NOT (G <= 12) 

—G is not less than or equal to 

12; value is 0 for false 


NOT (YEARZ > 1950) 

—the value of YEAR 1 is not 
greater than 1950 


Notice that the 0 R operator doesn’t correspond exactly to the way we 
often use the word “or” in everyday speech. When we say “A or B is 
true,” we usually mean that exactly one of the two statements is true, but 
not both. The Applesoft 0 R operator produces a “true” value if either or 


both of the original expressions are true. 
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0 means false 


Any nonzero value means true 


2.3.4 


Table 2-3 Precedence of Operators 


More Truth about Applesoft: Applesoft’s logical operators consider a 
numerical value of 0 to mean “false”; any numerical value other than 0 
is taken to mean “true.” The logical operators always yield a value of i 
for true or 0 for false. 


Logical operators are particularly useful in connection with the 
IF... T H E N statement, discussed in Section 3.2.2. 


Precedence of Operators 

Operators in Applesoft have an order o\ precedence that determines 
which operations are carried out first when they are combined in an 
expression. Table 2-3 lists the operators in descending order of prec¬ 
edence. Operators shown higher in the list are carried out before 
those lower down. Operators on the same line of the list have the 
same precedence, and are carried out from left to right within an 
expression. 


Parentheses (innermost first) ( ) 

Signed arithmetic and logical NOT + - NOT 


Exponentiation (powers of 
numbers) 

Multiplication and division 
Addition and subtraction 
Relational operators 
Logical AND 
Logical OR 


* / 

4- - 

= < > <= =< >= 

AND 

OR 


=> <> >< 


Notice in Table 2-3 that the operators + and - have higher precedence 
when used to represent the sign of a single number (as in + 14 4 or 
“ K) than when they stand for the addition or subtraction of two 
numbers. 

To understand how Applesoft’s precedence rules work, consider the 
expression 

-2*Z-3 + 0/ 5- A*B 

When Applesoft evaluates this expression, it begins by applying the 
first minus sign to the constant 2, obtaining a result of - 2. Next It 
raises the value of Z to the 3rd power and multiplies the result by 
- 2. Then it divides the value of 0 by 5 and adds the result to that of 
the previous calculation. Finally, it multiplies the values of A and B 
and subtracts that result from the previous one. 
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For example, suppose the current values of the variables in the 
expression above are as follows: 2 = 2,0 = 10, A = 7,8 = 4. 
Then 


— 2 



_ _ fp 

Z - 3 


= 2-3 

= 8 

-2*8 



CD 

•pH 

1 

II 

0/5 


= 10/5 

_ o 

- IS -1- 

*7 


II 

1 

1—1. 

A * B 


= 7*4 

= 28 

-14 - 

28 


= -42 


The value of the expression is -42. 

Parentheses change order of Parentheses can be used to change the normal order of precedence, 

evaluation For example: 

-2*Z'-(3 + 0)/5-A*B 

—value is - 3304.8; 

(3 + 0) evaiuated as a 
unit 

-2*Z'-3+(0/5-A)*B 

—value is -38; 

(0 / 5 - A) evaluated 
as a unit 

-2*Z"3 + 0/(5-A*B) 

—valueis - 1G.434782B; 
(0 / (5 - A * B) ) 
evaiuated as a unit 

The original expression above is equivaient to the fuliy parenthesized 
expression 

(((-2) / (Z - 3)) + (0 / 5)) - (A * B) 

Helpful Hint: When you’re unsure of the order of precedence, use pa¬ 
rentheses to make sure the expression is evaluated in the order you 
intend. 

Functions 

2.4 

Functions are preprogrammed caicuiations that can be carried out 

!hTc?n"beX%7oSTreSsT'^ can use them whenever you need to perform the 

same caicuiation repeatediy throughout a program. Whenever you 
ca// a function (request its execution), you must give it a particular 
value to operate on; this value is calied the argument of the function. 
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2.4.1 


Calling built-in functions 


A B S computes the absolute value 


Applesoft offers a variety of built-in functions, discussed in Section 
2.4.1, for calculating common mathematical values such as loga¬ 
rithms, cosines, and square roots. Section 2.4.2 covers the built-in 
function RND, used for generating random numbers. In addition, you 
can define your own functions for the special needs of a particular 
program—see Section 2.4.3 for details. 


Built-in Arithmetic Functions 

This section discusses the various buiit-in functions that Applesoft 
provides for calculating commonly used mathematical quantities. To 
call a built-in function, just type the name of the function followed by 
an expression in parentheses representing the argument value on 
which you want the function to operate. For example, suppose you 
need to calculate the square root of a number. Applesoft has a built-in 
function named SQR for this purpose; to find the square root of 3, 
write 

SOR (3) 

To find the square root of the value of variable X plus 2, write 
SOR (X-l-2) 

The ABS Function 

The built-in function ABS computes the absolute value of a num¬ 
ber—that is, the positive numerical value of the number, without re¬ 
gard to its original sign. For example. 


ABS 

(27) 

—absolute value of 2 7; yields 
27 

ABS 

( -27) 

—absolute value of - 2 7; yields 
27 

ABS 

(3B.8 - 23.3) 

—absolute value of 38.8 
minus 23.3;yields 13.5 

ABS 

(23.3 - 3G.8) 

—absolute value of 23.3 
minus 38.8; yields 13.5 

ABS 

(C7.(3) ) 

—absolute value of element 8 of 


array C% 
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The SGN Function 


S G N computes the sign of a number 


IN T computes the integer part of a 
number 

integer: a whole number 


The SGN function determines whether the value of its argument is 
positive, negative, or zero. It yields a result of 1 if the argument value 
is positive (greater than 0), - 1 if the argument value is negative 
(less than 0), and 0 if the argument value is 0. For example. 


SGN 

(27) 

—sign of 27; yields 1 (positive) 

SGN 

( -27) 

—sign of - 2 7; yields - 1 
(negative) 

SGN 

(3G.8 - 23.3) 

—sign of 38.8 minus 23.3; 
yields 1 (positive) 

SGN 

(23.3 - 3B.8) 

—sign of 23.3 minus 38.8; 
yields -1 (negative) 

SGN 

(3 * 5 - 45) 

—sign of 9 times 5 minus 45; 
yields 0 

SGN 

(SUM - 20) 

—sign of S U M minus 2 0 

The INT Function 



I NT yields the integer (whole-number) part of its argument value, 
with the fractional part (if any) discarded. Note that this function 
makes no attempt at rounding: that is, if the argument value is not an 
integer, I NT yields the riexf/owesf/nfege/; not necessarily the near¬ 
est integer. For example. 


INT 

(27) 

—integer part of 2 7; yields 2 7 

INT 

(38.8) 

—integer part of 3 8.8; yields 
38 

INT 

(-7.9) 

—Integer part of - 7.9; yields 
-8 

INT 

(-82.1 ) 

—integer part of - 82.1; yields 
-83 

INT 

(5 * PRICE) ’ 

—integer part of 5 times 

PRICE 


Rounding a Number: To round a numeric value to the nearest integer, 
first add . 5 and then apply the I NT function to the result. For example, 
to find the nearest integer to the current value of variable AGE, use the 
expression 

INT (AGE -F .5) 
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S Q R computes the square root 


The SOR Function 


The SOR function computes the positive square root of its argument. 
For example, 



SQR (IBS) 

—square root of 1G 3; yields 13 


SOR (1G3.84) 

—square root of 1B 3.8 4; 
yields 12.8 


SOR (3) 

—square root of 3; yields 
1.73205081 


SOR (K'-2 + 3) 

—square root of X squared plus 
3 

Square root of a negative number is an 
error 

If you try to take the square root of a negative number, an ILLEGAL 
QUANTITY error will occur. 


The SIN Function 


SIN computes the sine 

SIN computes the trigonometric sine of its argument. The argument 
must be expressed in radians. For example, assuming the value of 
thevariablePI is3.141532G5, 


SIN (PI / 3) 

—sine of PI / 3 radians; 
yields .8BB025403 


SIN (1) 

—sine of 1 radian; yields 
.841470385 


SIN (>('-2 - Y'-2) 

—sine of K squared minus Y 


squared 

The argument you supply to the SIN function must be expressed in ra¬ 
dians, not degrees. (There are 211 radians in a circle; one radian is equal 
to approximately 57.2957795 degrees.) For a formula you can use to 
convert from degrees to radians, see Section 2.4.3, “Defining Your Own 
Functions: The DEF FN Statement.” 


The COS Function 

COS computes the cosine COS computes the trigonometric cosine of its argument. The argu¬ 

ment must be expressed in radians. For example, assuming the 
value of the variable PI is3.141532G5, 


COS 

(PI / 3) 

—cosine of PI / 3 radians; 
yields . 5 

COS 

( 1 ) 

—cosine of 1 radian; yields 


.540302306 


Arguments to trig functions must be in 
radians, not degrees 
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_ 

Arguments to trig functions must be in 
radians, not degrees 

cos ( X " 2 - Y ■■■ 2 ) —cosine of X squared minus Y 

squared 

The argument you supply to the C 0 S function must be expressed in ra¬ 
dians, not degrees. (There are 2 it radians in a circle; one radian is equal 
to approximately 57.2957795 degrees.) For a formula you can use to 
convert from degrees to radians, see Section 2.4.3, “Defining Your Own 

Functions: The D E F F N Statement.” 

TAN computes the tangent 

The TAN Function 

TAN computes the trigonometric tangent of its argument. The argu¬ 
ment must be expressed in radians. For example, assuming the 
value of the variable PI is 3.141592B5, 

TAN (PI / 3) —tangent of PI / 3 radians; 

yields 1.7320508 

TAN ( 1) —tangent of 1 radian; yields 

1.55740772 

TAN ( X ■” 2 - Y " 2 ) —tangent of X squared minus Y 

squared 

Arguments to trig functions must be in 
radians, not degrees 

The argument you supply to the T A N function must be expressed in ra¬ 
dians, not degrees. (There are Zir radians in a circle; one radian is equal 
to approximately 57.2957795 degrees.) For a formula you can use to 
convert from degrees to radians, see Section 2.4.3, “Defining Your Own 

Functions: The 0 E F F N Statement." 

AIN computes the arc tangent 

The ATN Function 

A T N computes the trigonometric arc tangent (inverse tangent) of its 
argument: that is, the angle whose tangent is equal to the given 
value. The result is expressed in radians. For example, 

ATN ( S 0 R ( 3 ) ) —arc tangent of the square root 

of 3; yields 1.04719755 
(= PI / 3)radians 

ATN (1) —arc tangent of 1; yields 

. 7853981B3 radians 

ATN ( X ■■■ 2 — Y ■■■ 2 ) —arc tangent of X squared 

minus Y squared 

Result of A T N function is in radians, not 
degrees 

The result produced by the A T N function is expressed in radians, not 
degrees. (There are 211 radians in a circle; one radian is equal to approx¬ 
imately 57.2957795 degrees.) For a formula you can use to convert from 
radians to degrees, see Section 2.4.3, “Defining Your Own Functions: 

TheDEF FN Statement.” 
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The EXP Function 


E X P computes the exponential 


E X P accurate to six places 


LOG computes the natural logarithm 


Logarithm of a nonpositive number is an 
error 


2.4.2 


RND generates random numbers 


The EXP function computes the mathematical exponential of its ar¬ 
gument. The exponential is defined as the constant e raised to the 
power of the argument, where e = 2.718281828. For example, 


EXP 

(3) 

—e to the 3rd power; yields 
20,0855389 

EXP 

(L0G(10)) 

—e to the power of the natural 
logarithm of 10; yields 10 

EXP 

(A ♦ T) 

—e to the power A * T 


Limited Accuracy: Although Applesoft will display the result of the 
EXP function to nine places, only the first six are actually reliable. For 
instance, in the first example above, the computed result of 
20.08553B9 should be interpreted simply as 20.0855. 


The LOG Function 

LOG computes the natural logarithm of its argument (the logarithm to 
the base e, where e = 2.718281828.) For example. 


LOG (10) —natural logarithm of 10; yields 

2.30258509 

LOG (EXPO)) —natural logarithm of e to the 

3rd power; yields 3 

LOG (SIN(THETA)) —natural logarithm of the sine of 

THETA 


If you try to take the logarithm of a zero or negative number, an 
ILLEGAL QUANTITY error will occur. 


Generating Random Numbers: The RND 
Function 

The built-in function RND produces random decimal numbers be¬ 
tween 0 and 1. The behavior of this function depends on whether the 
argument you give it is positive, zero, or negative. 

The simplest way to use R N D is to give it a positive argument. RND 
will produce a different random number each time you call It with a 
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Positive argument produces a different 
random number each time 


Zero argument repeats same result as 
previous call 


Negative argument starts new, repeat- 
able sequence 

seed: the value used to begin a 
sequence of random numbers 


positive argument. The actual numeric value of the argument is ig 
nored; only its sign is significant: 


RND (1) 
RND <1) 
RND 09) 


—yields .431448496 
—yields .735966024 
—yields .345445325 


If you give R N D a zero argument, it will reproduce the same result as 
at the previous call: 


RND (99) 
RND (0) 
RND (0) 
RND (99) 
RND (0) 


—yields .270011996 
—yields .270011996 
—yields .270011996 
—yields . 139756248 
—yields . 139756248 


Calling RND with a negative argument causes it to begin a new, re¬ 
peatable sequence of random numbers. This is called seeding the 
random number generator; the particular negative value you use for 
the argument acts as a “seed” for the new sequence. Different seeds 
will produce different sequences, but each time you use the same 
seed you will get the same result. Subsequent calls to R N D with posi¬ 
tive arguments will then produce the same sequence of results: 


RND 

( - 1 ) 

—yields 2.9919S472E-08 

RND 

( 1 ) 

—yields .738207502 

RND 

( 1 ) 

—yields .272707136 

RND 

( 1 ) 

—yields .299733446 

RND 

( -5) 

—yields 3.73720468E-08: 
starts new sequence 

RND 

( 1 ) 

—yields .407457285 

RND 

( 1 ) 

—yields .463740324 

RND 

( 1 ) 

—yields .387195686 

RND 

( - 1 ) 

—yields 2.99196472E-08; 
repeats same sequence as 
before 

RND 

( 1 ) 

—yields .738207502 

RND 

( 1 ) 

—yields .272707136 

RND 

( 1 ) 

—yields .299733446 


Scientific Notation : The suffix E - 0 8 in some of the random values 
listed above means “times 10 to the minus-8th power,” and is an exam- 
pie of the scientific notation that Applesoft uses to display certain num¬ 
bers. See Section 1.2 for further details. 
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DEF FN defines a new function 

argument: the value on which a function 
operates 


Formula limited to 239 characters 

Argument must be a real variable 


Defining Your Own Functions: The DEF FN 
Statement 

DEF FN CUBE (K) =>(*)<* K 


In addition to the built-in functions discussed in Sections 2.4.1 and 
2.4.2, Applesoft gives you the ability to define your own functions for 
the special needs of a particular program. Defining your own func¬ 
tions can be a real time-saver: instead of writing out the same com¬ 
plex formula over and over again, you can simply define it once as a 
function, give it a name, and then refer to it by that name whenever 
you need it. 

To define a function of your own, use the D E F F N statement. This 
statement consists of the keywords DEF F N (for “define function”) 
followed by the name of the function you’re defining, the argument 
name enclosed in parentheses, an equal sign {=), and the formula 
defining the function. The examples below define functions to convert 
temperatures from Fahrenheit to Celsius and vice versa, and to con¬ 
vert angles from degrees to radians and vice versa, assuming that 
the value of the variable PI is3» 141592B5: 


10 

DEF 

FN 

FTC 

(T) 

= (T - 32) * 5 / 9 
—Fahrenheit to Celsius 

20 

DEF 

FN 

CTF 

(T) 

= T * (9 / 5) +32 
—Celsius to Fahrenheit 

30 

DEF 

FN 

DTR 

(A) 

= A * (PI / 180) 

—degrees to radians 

40 

DEF 

FN 

RTD 

(A) 

= A * (180 / PI) 

—radians to degrees 


For example, the definition above for function FTC says “to convert 
from Fahrenheit to Celsius, take the value of the argument (T), sub¬ 
tract 32, multiply by 5, and divide by 9.” 

The formula defining a function must not exceed one program line (239 

characters) in length. 

The names you give to your functions must follow the same rules 
given in Section 2.1.1 for variable names: the name may be as long 
as you like (up to 239 characters), but Applesoft uses only the first 
two characters to distinguish one function from another. The argu¬ 
ment variable in the function definition must be a real variable— 
integer and string variables (ending in 1 or $) are not allowed. 
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Don’t begin function names with the 
same first two characters 


Calling defined functions 


Take care not to begin the names of different functions with the same 
two characters, Applesoft will consider the names CODFISH and 
C 0 U N T, for example, to refer to the same function, since they both be¬ 
gin with the same two characters. If you try to define functions with these 
two names, the second definition will redefine the function, causing the 
first definition to be forgotten. 

However, a program can have a function and an array beginning with the 
same two characters (or even having exactly the same name). This is 
because references to the function are written with the keyword F N (see 
below), but references to the array aren’t. Thus Applesoft can tell that, 
for example, 

FN COUNT (N) 

is a call to the function named COUNT, whereas 
COUNT (N) 

is a reference to the array of the same name. 


The D E F F N statement can be executed only from within a pro¬ 
gram; you can’t use this statement in immediate execution. 

To call a function that you’ve defined with D E F F N, type the key¬ 
word F N (for “function”) followed by the name of the function and an 
expression in parentheses representing the argument value on 
which you want the function to operate. For example, using the func¬ 
tions defined above, 


FN 

FTC 

(98.B) 

—convert 98 . G degrees Fahr¬ 
enheit to Celsius: yields 3 7 

FN 

CTF 

(100) 

—convert 100 degrees Celsius 
to Fahrenheit; yields 212 

FN 

DTR 

(180) 

—convert 180 degrees to radi¬ 
ans; yields 3. iai592B5 

FN 

RTD 

(PI / 2) 

—convert PI / 2 radians to 
degrees; yields 90 


Notice that the keyword F N must be used in calling your own defined 
functions, but not for built-in functions (see Section 2.4.1, “Built-in 
Arithmetic Functions”). 
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Chapters 


Control statements determine the 
order of program execution 


unconditional branching: see 

Section 3.1 


conditional branching: see Section 3.2 


loops: see Section 3.3 


subroutines: see Section 3.4 


error handling: see Section 3.5 


program termination: see Section 3.6 


Control Statements 


Ordinarily, Applesoft programs are executed sequentially, from the 
lowest-numbered line to the highest. Control statements allow you to 
branch to another part of the program: that is, to alter the normal or¬ 
der of execution and send control to a line of the program other than 
the next line in sequence. This ability to change the course of pro¬ 
gram flow is what gives computer programs their real power and 
flexibility. 

Section 3.1, “Unconditional Branching: The GOTO Statement,” deals 
with the G 0 T 0 statement, which sends control unconditionally to a 
specified line of the program. 

Section 3.2, “Conditional Branching,” discusses conditional branch¬ 
ing statements, which allow the program to decide what to do next by 
evaluating an expression or testing for a condition. 

Section 3.3, “Loops,” covers statements that are used in loops (por¬ 
tions of a program that are executed many times repeatedly). 

Section 3.4, “Subroutines,” deals with the very important subject of 
subroutines: sections of a program that can be executed on request 
from elsewhere in the program to perform some particular task. 

Section 3.5, “Error Handling,” describes Applesoft’s facilities for de¬ 
tecting and dealing with error conditions that arise during the execu¬ 
tion of a program. 

Finally, Section 3.6, “Program Termination,” covers the various ways 
of terminating (ending) the execution of a program. 
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3.1 


unconditional branch: a branch that 
does not depend on the truth of any 
condition 


GOTO branches to a specified line 
number 


infinite loop: a section of a program that 
will repeat the same sequence of actions 
indefinitely 


Unconditional Branching: The GOTO 
Statement 

GOTO 100 


An unconditional branch sends control to a specified iine of the pro¬ 
gram without reference to whether any particuiar condition holds. 
Applesoft has two statements that cause an unconditional branch: 
GOTO and GOSUB.TheGOTO statement is described in this sec¬ 
tion; see Section 3.4.1 for a description of the GOSUB statement. 

The GOTO statement interrupts the normal sequential execution of 
program lines and forces execution to branch to (go to) a specified 
iine number. The branch is unconditional: that is, it doesn’t depend on 
the truth or falsity of any particuiar condition. 

For exampie, consider the foiiowing program: 


10 

PRINT 

"HELLO" 

20 

PRINT 

"THERE" 

30 

GOTO 

10 

40 

PRINT 

"FRIEND 


—display the word HELLO 
—display the word THERE 
—branch to line 10 
—this iine never executed 


This program dispiays the word H E L L 0 on the screen (line 10), dis¬ 
plays the word THERE (line 20), and then (iine 30) goes back to 
iine 10 to repeat the process. The word FRIEND never gets dis¬ 
played, because program execution never reaches line 40. Instead, 
the program simply repeats lines 10 to 30 indefiniteiy, displaying the 
words HELLO and THERE over and over again on the screen. 

The program above contains an example of an infinite loop. To stop the 
program and regain control of the computer, press | control | -C. 


If your program attempts to branch to a nonexistent line, or if a G 0 T 0 
statement does not include a line number, an error message such as 

?UNDEF'D STATEMENT ERROR IN 30 

will appear. Identifying the program line in which the error occurred. The 
program will stop and Applesoft will return to command level: 


10 

PRINT 

"HELLO“ 


20 

PRINT 

"THERE" 


30 

GOTO 

15 

—branch to non-existent line 

40 

PRINT 

"FRIEND" 
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3.2 

conditional branch: a branch that de¬ 
pends on the truth of a condition or the 
value of an expression 

□ N...G □ T 0 statement: see Section 
3.2.1 


0 N...G 0 S U B statement: see Section 
3.4.3 


I F...THEN statement: see Section 
3.2.2 


3.2.1 


0 N...G 0 T 0 chooses where to branch 
depending on the value of an 
expression 


If value out of range, control proceeds 
sequentially 


You Can’t Branch to a Variable: If you attempt to use a variable instead 
of an actual line number to specify the line to which a branch should oc¬ 
cur (as in G 0 T 0 J), Applesoft will always attempt to branch to line 
number 0, no matter what value the variable holds. If line 0 doesn’t ex¬ 
ist, an UNDEF ' D STATEMENT error will occur: 


5 

LET J 

= 10 

—assign value to variable 

10 

PRINT 

"HELLO" 


20 

PRINT 

"THERE" 


30 

GOTO J 


—Applesoft will try to go to line 
number 0 

40 

PRINT 

"FRIEND" 



Conditional Branching 

A conditional branch decides what action to take next, depending on 
the truth of a stated condition or on the value of an arithmetic expres¬ 
sion. Applesoft has three statements that cause a conditional branch: 

• 0 N...G 0 T 0 branches to one of a number of possible program 
lines, depending on the value of an arithmetic expression. 

• 0N...G0SUB branches to one of a number of possible subrou¬ 
tines, depending on the value of an arithmetic expression. 

• IF... T H E N either executes or skips one or more statements, 
depending on the truth of a stated condition. 


The ON...GOTO Statement 

ON X GOTO 150» 200» 310» 310» 150» 099 
ON S% - 7 GOTO 300* 295» 900> 150 


The 0N...G0T0 statement sends control to one of a list of line num¬ 
bers, depending on the integer value of an arithmetic expression. The 
expression between the keywords 0 N and G 0 T 0 is evaluated; if the 
result is real it is truncated to an integer. If this value is between 1 and 
the number of line numbers in the list, program execution branches to 
the line number at the corresponding position in the list. (For exam¬ 
ple, if the integer value of the expression is 3, execution branches to 
the third line number in the list.) If the integer value of the expression 
is 0 or is greater than the length of the list, execution continues with 
the next statement following the DN...G0T0. 
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The following program illustrates the use of ON...GOTO: 


I F...THEN executes or skips, de¬ 
pending on the truth of a condition 


10 

20 

INPUT X 

ON X GOTO 150 

, 2 

30 

PRINT "MALUE 
RETYPE: " 

OUT 

40 

150 

GOTO 10 

PRINT "MALUE 

IS 

IGO 

200 

GOTO 10 

PRINT "MALUE 

IS 

210 

310 

GOTO 10 

PRINT "MALUE 

IS 

320 

999 

GOTO 10 

END 



—get number from keyboard 
00 » 310 » 310 » 150 » 999 
—decide where to go, depend¬ 
ing on value of X 

OF RANGE» PLEASE 
—control comes here if X = 0 or 
X>G 

—start again 
1 OR 5" 

—control comes here if X = 1 or 
X = 5 


—control comes here if X = 2 
3 OR a" 

—control comes here if X = 3 or 
X = a 

—control comes here if X = G 


If the integer value of the expression between 0 N and GOTO is less 
than 0 or greater than 255, an ILLEGAL QUANT ITY errorwill 
occur and program execution will halt. 


The IF...THEN Statement 

IF Z > 255 THEN END 

IF HX - 23 < SM - TTL THEN KX = 

HX - 23 : HX = 0 
IF X (I) = 12 THEN GOTO 325 

IF A$ >< THEN 300 

IF (D > ,05) AND NOT (E > .1) GOTO 2150 


The IF...THEN statement tests for the condition given between the 
keywords IF and THEN. If the condition is true, the statement or 
statements following T H E N in the same program line are executed. 
If the condition is false, the remainder of the line following T H E N is 
skipped and execution continues with the next program line in 
sequence. 
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When the statement following THENisaGOTO, either (but not both) of 
the keywords THEN and GOTO may be omitted. The following state¬ 
ments are all equivalent: 

IF K (I) = 12 THEN GOTO 325 

IF X (I) = 12 THEN 325 

IF X (I) = 12 GOTO 325 

Notice that when the IF condition is false, program execution contin¬ 
ues with the next program line (not the next statement) in sequence. 
No other statements in the IF line are carried out: 

10 LET J = 1 : K = 2 
20 LET A = 10 —Asetto 10 here 

30 PRINT ■■ J HOLDS "5 J! " AND K 
HOLDS " ; K 

40 IF A > 10 THEN J = 5: K = 10: 

GOTO 100 —A is not greater than 10; test 

fails 

50 PRINT "THE VALUES OF J AND K ARE 

UNCHANGED* " —this message gets printed 

SO GOTO S90 

100 PRINT "J NOW HOLDS J? " AND K 
HOLDS "5 K —this message not printed 

999 END 

When the program above is run, the IF test in line 40 will fail, the 
values of J and K will not be changed, and execution will continue 
with line 50. If line 20 were changed to 

20 LET A = 25 

then the IF test in line 40 would succeed, the values of J and K 
would be changed, and control would branch to line 100. 
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0 means false 


Any nonzero value means true 


Using Numeric Values In IF...THEN: The I F...THEN statement 
considers a numeric value of 0 to mean “false”; any nonzero value is 
taken to mean “true.” Thus you can write statements such as 

IF J THEN GOSUB 400 

which Is equivalent to 

IF J <> 0 THEN GOSUB 400 

Recall also that Applesoft’s relational and logical operators always yield 
a value of 1 for true and 0 for false. Thus you can combine numeric val¬ 
ues with the logical operators: the statement 

IF NOT J THEN GOTO 500 

is equivalent to 

IF J = 0 THEN GOTO 500 
and 

IF A AND B THEN END 
is equivalent to 

IF (A <> 0) AND (B <> 0) THEN END 

Numeric values used in this way offer two advantages over the corre¬ 
sponding relational expressions: 

• They take up less space in memory. 

• They execute somewhat faster. 

See Appendix G for further hints on making your programs more effi¬ 
cient, 


Curious Parsing: Applesoft gets confused if the keyword f H E N is im¬ 
mediately preceded by a variable name ending in the letter A. For exam¬ 
ple, the statement 

IF J = BETA THEN 230 

will be interpreted as 

IF J = BET AT HEN230 

causing a syntax error. This is because A T and T H E N are both re¬ 
served words; in the example, the word A T is encountered first, so it is 
interpreted first. Such is life with Applesoft. You can get around the prob¬ 
lem by using parentheses: 

IF (J = BETA) THEN 230 
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3.3 


loop: a sequence of statements exe¬ 
cuted repeatedly 

pass: a single execution of a loop 


index variable: a variable whose value 
changes on each pass through a loop; 
often called control variable or loop 
variable 


NEXT statement: see Section 3.3.2 


body: the statements in a loop between 
the FOR and NEXT statements 


Loops 

A loop is a sequence of statements in a program that are executed 
repeatedly, often with the value of some variable being changed on 
each pass through the loop. Loops are fundamental to all computer 
programming: it’s practically impossible to write any kind of useful or 
interesting program that doesn’t include at least one loop. 

The usual way of writing loops in Applesoft is with the F 0 R and 
NEXT statements. The FOR statement marks the beginning of the 
loop. It identifies the loop’s index variable (the variable whose value 
changes on each pass) and gives the starting and ending values the 
index variable is to take on. Sometimes it also specifies the amount 
by which the value of the index variable is to change on each pass 
(see Section 3.3.1, “The FOR Statement,” for details). 

The NEXT statement marks the end of the loop and causes the loop 
to be executed again for the next value of the index variable. When 
the loop has been executed once for each value of the index variable, 
as specified in the FOR statement, control “falls through” to the next 
statement following the NEXT statement. (That’s right, “the next 
statement following the N E X T statement.”) 

Here’s an example to show how loops work: 


5 

10 

20 

30 

ao 

50 

BO 

70 

80 


PASS = 0 —initialize pass count 

FOR X = 3 TO 10 —execute loop once for each 

value of X from 3 to 10 

PASS = PASS + 1 —count passes through the loop 

PRINT “PASS #"5 PASS 

—display pass count 
PRINT "INDEX = X 


—display current value of index 
variable X 

PRINT —display blank line (for 

neatness) 

NEXT X —repeat loop for next value of X 

PRINT "LOOP FINISHED" 

—control comes here after last 
pass through loop 


END 


The loop begins with the F 0 R statement in line 10, which specifies 
that the loop is to be executed once for each value of index variable X 
from 3 to 10. Lines 2 0 to 5 0 form the body of the loop. The NEXT 
statement in line B 0 marks the end of the loop and sends control 
back to line 2 0 for the next value of X. After the loop is executed for 
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the last time, with X set to the specified ending value of 10, X is in¬ 
creased to 11. Since this exceeds the ending value, control “falls 
through” the NEXT statement to line 70. 

When the program above is executed, it will display the following 
results on the screen: 


PASS #1 
INDEX = 

PASS #2 
INDEX = 

PASS #3 
INDEX = 

PASS #4 
INDEX = 

PASS #5 
INDEX = 

PASS #B 
INDEX = 

PASS #7 
INDEX = 

PASS #8 
INDEX = 

LOOP Fir 


Be careful jumping out of loops Loop Before You Leap: Exiting from the middle of a F 0 R/N E X T loop 

before the index variable reaches the ending value leaves Applesoft ex¬ 
pecting a resolution that never comes. This is a dangerous practice that 
can cause unpredictable results in your program’s execution. Don’t write 
loops of the form 

10 FOR INDEX = LOW TO HIGH 

20 LET COUNT = COUNT + 1 

30 IF COUNT ^ LIMIT THEN GOTO 100 

—not recommended 

40 NEXT INDEX 

To be on the safe side, it’s better to finish the loop this way: 

30 IF COUNT = LIMIT THEN INDEX = HIGH: 
NEXT INDEX: GOTO 100 
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3.3.1 

The FOR Statement 

FOR Y = 1 TO 10 

FOR MASS = 3.5 TO 7 STEP 1.5 

FOR YEAR = 1980 TO 19B0 STEP -4 

FOR M = A + 2 TO 2*B - 3 STEP C / 2 

FOR marks the start of a loop 

The FOR statement marks the beginning of a loop, identifies the 

index variable: a variable whose value 
changes on each pass through a loop; 
see Section 3.3, above 

loop’s Index variable, and gives the starting and ending values of the 
index variable. It may also optionally specify the step value, the 
amount by which the value of the index variable is to change on each 
pass through the loop. If no step value is given, a value of 1 is 
understood. 

step value: the amount by which the 
index variable changes on each pass 
through a loop 

In the example in Section 3.3 above, no step value was given, so the 
index variable X was incremented by 1 on each pass through the 
loop. If line 10 in the example were changed to 

10 FOR X = 3 TO 10 STEP 2 

—execute loop once for each 
value of X from 3 to 10 by 2 

the program would produce the following output on the display 
screen: 

PASS #1 

INDEX = 3 

PASS #2 

INDEX = 5 

PASS #3 

INDEX = 7 

PASS #4 

INDEX = a 

LOOP FINISHii 


The loop is executed four times, with the index variable taking on val¬ 
ues of 3, 5, 7, and 0. At the end of the fourth pass, the index variable 
exceeds the specified ending value (3 plus 2 is 11, which is greater 
than the ending value of 10), so the loop ends and execution contin¬ 
ues with the statement following the N E X T in line B 0. 
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Body of loop always executed at least 
once 


Step value may be negative 


Index variable must be a real variable 


Applesoft Will Try Anything Once: Notice that the test to see whether 
the index variable exceeds the ending value is carried out at the end of 
the loop. This means the body of the loop will always be executed at 
least once. Even if the specified starting value is greater than the ending 
value, as in 

10 FOR X = 10 TO 3 —starting value exceeds ending 

value 

it won’t be discovered until after the loop has been executed once (10 
plus 1 is 11, which is greater than 3). 

It’s also possible to specify a negative step value: 

10 FOR K = 10 TO 3 STEP -2 

—negative step value 

In this case the index variable will take values of 10, 8, G, and 4. 
When the step value is negative, the loop ends when the index value 
becomes less than the ending value (4 plus - 2 is 2, which is less 
than the ending value of 3). Notice that the starting and ending val¬ 
ues have been reversed; if the statement read 

10 FOR K = 3 TO 10 STEP -2 

—starting value less than ending 
value 

the loop would have been executed only once (3 plus - 2 is 1, which 
is less than 10). 

A step value of 0 will result in an infinite loop. To stop the program 
and regain control of the computer, press | control | -C. 

The index variable specified in a FOR statement must be a real vari¬ 
able. Attempting to use an integer variable, such as 

10 FOR >{“1 — 3 TO 10 —integer index variable 

will cause a syntax error at run time. (However, the expressions for 
the starting, ending, and step values are unrestricted; any or all of 
these values may be specified by an integer variable). 
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3.3.2 The NEXT Statement 


NEXT repeats execution of a loop 


3.3.3 

nested loop: a loop contained within the 
body of another loop 


NEXT 

NEXT INDEX 
NEXT J*I 


The NEXT statement marks the end of a loop and causes the loop to 
be repeated for the next value of the index variable, as specified in 
the corresponding FOR statement. When the vaiue of the index vari¬ 
able becomes greater than the specified ending vaiue (iess than the 
ending value if the step vaiue is negative), execution proceeds with 
the statement immediately following the NEXT statement. 

Naming the index variable in a N E X T statement is optional; if you 
omit it, Applesoft will automatically repeat the most recently entered 
loop. If you’re using nested loops, this means the innermost loop con¬ 
taining the NEXT statement will be repeated. 


Helpful Hint: Leaving out the index variable in NEXT statements will 
make your programs run slightly faster: 

10 FOR G = 1 TO B 
20 PRINT "W0W» MOM!" 

30 NEXT —no Index variable necessary 


Nesting of Loops 

F 0 R/N E X T loops can be nested one inside another to a maximum 
depth of ten levels. For example. 


10 

20 

30 


ao 

50 


A = 1 TO 3 —start of outer loop 

B = 1 T 0 2 —start of inner ioop 

1 a; " »B = "5 B 

—dispiay vaiues of index 
variabies 

B —repeat inner loop 

A —outer loop not repeated until 

inner loop is finished 


FOR 
FOR 
PRINT "A = 


NEXT 

NEXT 
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The inner loop (lines 2 0 to 4 0) is executed twice for each pass 
through the outer loop; the PR I NT statement in line 30 is executed 
six times in all. This program will display the following on the screen: 



A = 1 » B = 1 

A = 1 . B = 2 

A = 2 » B = 1 

A = 2 . B = 2 

A = 3* B = 1 
A = 3 . B = 2 


Although this example shows only two levels of nesting, Applesoft al- 


No more than 10 levels of nesting 


lows as many as ten levels (a loop inside a loop inside a loop... ten 
times). If you nest your loops to a depth greater than ten, your pro¬ 
gram will halt with the error message 

OUT OF MEMORY 


Nested loops must not cross each other—that is, each loop must be 


Don’t cross loops 


completely contained within the body of the next outer loop. Once a 
loop is started using a particular index variable, the corresponding 
NEXT must name the same index variable (if it names any at all). In 
the example above, if lines 40 and 50 were reversed 


—attempt to repeat outer loop 
—before inner loop is finished 


40 NEXT A 
50 NEXT B 


the program would halt with an error because of the crossed loops. 


Warning 

Cross-looping is a second-degree misdemeanor punishable by five min¬ 
utes in the penalty box and a NEXT WITHOUT FOR error. It will 
also melt your keyboard. 


When two or more N E X T statements occur in a row, as in the example 
above, you can combine them into a single NEXT statement of the form 

40 NEXT B>A —repeat inner, then outer loop 

Notice, however, that the index variables must be listed in the reverse or¬ 
der of their corresponding FOR statements, to avoid crossing loops. The 
statement 

40 NEXT A —whoops! 

will reduce your keyboard to a puddle of plastic. 
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J —\ 

3.4 

G0 SU B statement: see Section 3.4.1 
RETURN statement: see Section 3.4.2 

ON...GOSUB statement: see Section 
3.4.3 

POP statement: see Section 3.4.4 

GOTO statement: see Section 3.1 

point of call: the point in a program from 
which a subroutine is called 


Subroutines 

A subroutine is a section of a program that can be executed on 
request from another part of the program. Applesoft has four state¬ 
ments relating to subroutines: 

• G 0 S U B directs control to a particular subroutine. 

• RETURN sends control back to the statement following the 
G 0 S U B that branched to the subroutine. 

• ON...GOSUB selects one of a number of possible subroutines, 
depending on the vaiue of an arithmetic expression. 

• POP removes a return address from the top of the control stack 
(see the box below titled “How Subroutines Stack Up”). 

To call a subroutine (request its execution), branch to its first iine with 
a G 0 S U B statement. G 0 S U B differs from an ordinary G 0 T 0 in that 
it “remembers” where in the program the subroutine was called from, 
so that control can return to that point when the subroutine is finished. 
The same subroutine can be called from many different places in the 
program; when the subroutine is finished, it sends controi back to the 
statement following the proper point of call by executing a R E T U R N 
statement. 

Here’s an example to illustrate the idea: 

10 FOR Z = 1 TO 10 —execute loop 10 times 
20 LET K = INT (RND (1) * 100) 

—generate a random integer be¬ 
tween 0 and 39 

30 PRINT X " IS "5 —display first part of message 
40 IF X < 50 THEN GOSUB 1000 : GOTO BO 

—branch to subroutine at line 
10 0 0 if random number is 
less than 5 0; on return, go to 
line BO 


50 

GOSUB 

2000 


—branch to subroutine at line 





2 0 0 0 if random number is 
50 or greater 

BO 

PRINT 

"PASS 

#" 5 

Z: PRINT 

—count number of passes 





through loop 

70 

NEXT Z 



—repeat loop 

999 

END 



—end program 

1000 

PRINT 

"LESS 

THAN 

50" 


—print second part of message 
for numbers iess than 5 0 
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Control returns to statement (not line) 
following GO SUB 


Don’t use the back door 


nested subroutine call: a call to a sub¬ 
routine from within another subroutine 


1010 

RETURN 

—return to statement following 
point of call 

2000 

PRINT "HORE 

THAN 40" 

—print second part of message 
for numbers greater than 4 9 

2010 

RETURN 

—return to statement following 
point of call 


The loop in lines 10 to 7 0 generates a random integer between 0 
and 0 9, then calls one of the two subroutines at lines 10 0 0 and 
2000, depending on the value of the random number. Each of the 
subroutines displays an appropriate message, then returns control to 
the statement following the point of call with a R E T U R N statement 
(lines 1010 and 2010). The program then displays a count of the 
number of passes through the loop and repeats the loop from the be¬ 
ginning. When the loop has been executed ten times, the program ends. 

Notice that the R E T U R N statement returns control to the statement 
following the GOSUB statement, not just to the//ne following it. In line 
40 of the example above, if the random number generated is less 
than 50, control is directed to the routine at line 1000. When execu¬ 
tion returns from the subroutine, it will continue with the statement 
GOTO BO, branching around line 50. 

Every subroutine should be regarded as a separate, indivisible unit 
of your program, which should be entered only with a G 0 S U B and 
exited only with a R E T U R N. Jumping into or out of the middle of a sub¬ 
routine with an ordinary GOTO subverts Appiesoft’s orderly control 
stack mechanism (see “How Subroutines Stack Up,” below) and causes 
the programmer to be in a state of sin. People who indulge in such 
odious practices should be ostracized from polite society. 

Subroutine calls may be nested: that is, you can call one subroutine 
from inside another. Consider the following program: 


10 

GOSUB 

1000 

—branch to first subroutine 

20 

PRINT 

"BACK 

HONE AGAIN" 

—this message displayed last 

30 

END 


—prevent control from acci¬ 
dently “falling into” a 
subroutine 

1000 

PRINT 

"FIRST 

SUBROUTINE CALLED" 

—this message displayed first 

1010 

GOSUB 

2000 

—branch to second subroutine 


62 


Control Statements 




1020 PRINT "BACK AT FIRST SUBROUTINE" 

—this message displayed third 

1030 RETURN —return to statement following 

point of call (line 20) 

2000 PRINT "SECOND SUBROUTINE CALLED" 

—this message displayed 
second 

2010 RETURN —return to statement following 

point of call (line 1020) 

Line 10 calls the first subroutine, at line 10 0 0. This subroutine dis¬ 
plays the first message on the screen, then (line 1010) calls the 
second subroutine at line 2000. The second subroutine displays its 
message, then returns control (line 2 010) to the statement following 
the point of call in the first subroutine. The first subroutine then dis¬ 
plays another message and returns control (line 1030) to the state¬ 
ment following its point of call. The final message is then displayed 
(line 20) and the program ends. The lines of the program are exe¬ 
cuted in the following order: 

Line 10 
Line 1000 
Line 1010 
Line 2000 
Line 2010 
Line 1020 
Line 1030 
Line 20 
Line 30 

The program produces the following output on the screen: 



FIRST SUBROUTINE CALLED 
SECOND SUBROUTINE CALLED 
BACKAT FIRST SUBROUTINE 
BACK HOME AGAIN 


stack: a list in which entries are added or 
removed at one end only 

return address: the point to which con¬ 
trol returns on completion of a subroutine 

push: to add an entry to the top of a stack 

pop: to remove the top entry from a stack 


How Subroutines Stack Up: Applesoft maintains a control stack to 
keep track of the return addresses —the points to which control is to 
return on completion—for all subroutines in progress. Each time a 
G 0 S U B is executed, the location of the statement following the 
G 0 S U B is pushed onto the top of the stack. When a R E T U R N state¬ 
ment is executed, the top entry is popped from the stack and control is 
directed to that point in the program. This arrangement ensures that 
control enters and leaves subroutines In LIFO (last-in-first-out) order. 
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Subroutine calls can be nested up to 25 levels deep: that is, you can 
GOSUBfromaGOSUBfromaGOSUB ... 24 times. Attempting to 
go more than 25 levels deep will result in an OUT OF MEMORY 
error. 

Actually, you’re out of stack space, as opposed to program space. Since 
no rational BASIC program ever uses such complex nesting, this error 
usually means you’ve got a subroutine aecidentalty calling itself. 

3.4.1 

The GOSUB Statement 

GOSUB 1000 

G0SU5 branches to a subroutine 

The GOSUB (for “go to subroutine”) statement is used to branch to 
a subroutine, saving a return address to which controi can return 
when the subroutine is compieted. The location of the statement im- 

control stack: see Section 3.4 

mediately following G 0 S U B is pushed onto the control stack, and 
control is sent to the line number specified in the G 0 S U B statement. 

GOTO statement: see Section 3.1 

GOSUB differs from an ordinary G 0 T 0 in that it “remembers” where 
in the program the subroutine was called from, so that control can re¬ 
turn to that point with a R E T U R N statement when the subroutine is 
finished. 

AGOSUBtoa target line that doesn’t exist will cause a message such 
as 

?UNDEF'D STATEMENT ERROR IN 1350 

to be displayed, identifying the line number in which the error occurred, 
and your program will come to an untimely halt. 

3.4.2 

The RETURN Statement 

RETURN 

RETURN returns control from a 
subroutine 

The RETURN statement returns control from a subroutine to the 
statement following its point of call. The top entry is popped off the 

control stack: see Section 3.4 

control stack and control is sent to that return address. 

If the control stack is empty when R E T U R N is executed, your program 
will halt with the message 

?RETURN WITHOUT GOSUB 
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3.4.3 The ON...GOSUB Statement 


0N...G 0 S U 6 chooses a subroutine 
depending on the vaiue of an 
expression 


If value out of range, control proceeds 
sequentially 


ON X GOSUB 150f 200^ 310t 310^ 150* 999 
□N SX - 7 G09UB 300* 285* 900* 150 


The 0N...G0SUB statement sends contralto one of a list of subrou¬ 
tines, depending on the integer value of an arithmetic expression. 
The expression between the keywords ON and GOSUB is evaluated; 
if the result is real it is truncated to an integer. If this value is between 
1 and the number of line numbers in the list, program execution 
branches to the subroutine at the corresponding position in the list. 
(For example, if the integer value of the expression is 3, execution 
branches to the subroutine beginning at the third line number in the 
list.) If the integer value of the expression is 0 or is greater than the 
length of the list, execution continues with the next statement follow¬ 
ing the ON...GOSUB. 

The following program iilustrates the useof 0N...G0SUB: 


10 

INPUT X 

—get number from keyboard 

20 

ON X GOSUB 150» 

200 ♦ 310» 310» 150» 


999 

—decide where to go, depend¬ 
ing on value of X 

30 

IF X = 0 OR X > 

B THEN PRINT "VALUE 


OUT OF RANGE» 

PLEASE RETYPE:" 

—display message if X out of 
range 

ao 

GOTO 10 

—start again 

150 

PRINT "VALUE IS 

1 OR 5" 

—control comes here if X = 1 
orX = 5 

ISO 

RETURN 


200 

PRINT "VALUE IS 

—control comes here if X = 2 

210 

RETURN 


310 

PRINT "VALUE IS 

3 OR 4" 

—control comes here if X = 3 
or X = a 

320 

RETURN 


993 

END 

—control comes here if X = B 


Compare the program above with the example given for the 
0N...G0T0 statement in Section 3.2.1. The operation of 
ON...GOSUB is very similar to that of ON...GOTO, except that 
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RETURN statement: see Section 3.4.2 


3.4.4 

P D P removes top entry from control 
stack 

control stack: see Section 3.4 


0N...G0SUB “remembers” where in the program the subroutine was 
called from by pushing onto the controi stack the location of the next 
statement foliowing 0 N... G 0 S U B. Controi can then return to that 
point with a R E T U R N statement when the subroutine is finished. 

If the integer value of the expression between 0 N and G 0 S U B is less 
than 0orgreaterthan 255,an ILLEGAL OUANTITY errorwill 
occur and program execution will halt. 


The POP Statement 

POP 


The POP statement removes (pops) the top return address from the 
control stack without sending controi to that point. This causes the 
next RETURN statement to send controi back to the statement fol¬ 
iowing the point of the second most recent subroutine caii, instead of 
the most recent. 

Here’s an example illustrating the use of PO P: 


10 

GOSUB 

1000 

—branch to first subroutine 

20 

PRINT 

"BACK 

HOME AGAIN" 

—this message dispiayed iast 

30 

END 


—prevent controi from acci¬ 
dently “falling into” a 
subroutine 

1000 

PRINT 

"FIRST 

SUBROUTINE CALLED" 

—this message displayed first 

1010 

GOSUB 

2000 

—branch to second subroutine 

1020 

PRINT 

"BACK 

AT FIRST SUBROUTINE" 

—this message never displayed 

1030 

RETURN 


—this return never taken 

2000 

PRINT 

"SECOND SUBROUTINE CALLED" 

—this message dispiayed 
second 

2 0 0 5 

POP 


—remove return address from 
stack 

2010 

RETURN 


—return to statement foiiowing 
first subroutine’s point of call 


(iine 20) 

This program is identical to the one in Section 3.4 illustrating nested 
subroutine cails, except that a P 0 P statement (line 2 0 0 5) has been 
added to the second subroutine. The effect of the P 0 P is to remove 
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the second subroutine’s return address (line 10 2 0) from the control 
stack, causing the R E T U R N in line 2 010 to go back to the state¬ 
ment following the point of call of the first subroutine (line 2 0) in¬ 
stead. As a result, lines 1020 and 1030 are never executed, and 
the message BACK AT FIRST SUBROUTINE is neverdis- 
played. The lines of the program are executed in the following order: 

Line 10 

Line 1000 

Line 1010 

Line 2000 

Line 2005 

Line 2010 

Line 20 

Line 30 

The program produces the following output on the screen: 

FIRST SUBROUTINE CALLED 

SECOND SUBROUTINE CALLED 

BACK HOME AGAIN 

If the control stack is empty when P 0 P is executed, your program will 
haltwith a RETURN WITHOUT GOSUB error. 

Resist temptation 

Programming Tip: Although it’s sometimes tempting to try to get out of 
a tight programming situation by using POP, most good programmers 
avoid it, because it makes program flow really difficult to follow. If you 
find yourself becoming ensnared in convoluted code, ’tis a far better 
thing to redesign your program than to resort to the use of PO P. See 

Chapter 8 for a tutorial on program planning. 

] 1 . 

3.5 

Error Handling 

Sometimes even the most carefully written program will come to an 
embarrassing halt at an inopportune moment because of an error. If 
you’ve never suffered an “error crash,” you ain’t a programmer. Ap¬ 

ONERR GOTO statement : see Sec¬ 
tion 3.5.1 

plesoft’s ONERR GOTO and RESUME statements provide a mech¬ 
anism for detecting program errors as they occur and dealing with 

RESUME statement: see Section 3.5.2 

them from within your program. Using these statements, you can 
make your program dispiay its own error messages or take any other 
action you consider appropriate, instead of coming to a sudden, 
screeching stop. 
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3.5.1 r/ieONERR GOTO Statement 

ONERR GOTO 20000 


ONERR GOTO allows program to 
handle errors 


error code: a number representing a 
type of error 

Error code stored at location 222 

meanings of errors: see Appendix E 
Table 3-1 Error Codes 


The ONERR GOTO statement turns off Applesoft’s normal error 
handling and replaces it with an error-handling subroutine in your 
program. After this statement is executed, program errors will no 
longer stop the program, but will instead transfer control to the error 
routine beginning at the specified line number. 

Before sending control to the error routine, Applesoft stores an error 
code identifying the type of error at a special location in the comptu- 
ter’s memory, location 222. The error routine can then look at the 
contents of this location with the P E E K function and decide what ac¬ 
tion to take, depending on the error. Table 3-1 lists the possible error 
codes and their meanings. See Appendix E, “Error Messages,” for 
further information on the conditions that cause each type of error. 


Code 

Meaning 

Code 

Meaning 

0 

NEXT without FOR 

120 

Redimensioned array 

IG 

Syntax 

133 

Division by zero 

22 

RETURN without GOSUB 

163 

Type mismatch 

42 

Out of data 

176 

String too long 

53 

Illegal quantity 

191 

Formula too complex 

69 

Overflow 

224 

Undefined function 

77 

Out of memory 

254 

Bad response to INPUT 

90 

107 

Undefined statement 

Bad subscript 

255 

statement 

1 CONTROL 1-C interrupt attempted 
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To prevent an error from interrupting the program, the D N E R R 
GOTO statement must be executed before the error occurs. If you’re 
using 0 N E R R GOTO, it’s a good idea to make it one of the first lines 
in your program, as in the following example: 

10 ONERR GOTO 21500 

—establish error routine at line 
21500 


21500 LET EC=PEEK (222) 

—get error code 

21510 IF EC <> 255 THEN 21550 

—branch if not | control1 -C 

21520 PRINT "S0RRY--PR0GRAM CAN'T BE 
STOPPED WITH CONTROL-C" 

—if user pressed | control | -C , 
display special message 


21530 

RESUME 

—and resume program 

21550 

PRINT " 

UNANTICIPATED ERROR» 


CODE 

" ? EC —on any other error, display 



general message 

215G0 

STOP 

—and halt 


The program above uses its own error-handling routine to prevent the 
I CONTROL l -C: see Sectioni. 3.2 user from interrupting execution by pressing | control | -C. Line 10 

turns off Applesoft’s normal error handling and substitutes instead 
the program’s own error routine, beginning at line 21500. If an error 
later occurs, the first thing the error routine does (line 215 0 0) is get 
the error code from memory location 2 2 2 to find out what type of er¬ 
ror occurred. The error code is assigned to variable E C to make It 
easier to handle. Line 21510 tests for an error code of 2 5 5, mean¬ 
ing “ I coNTROL~l -C interrupt attempted” (see Table 3-1). If the error Is 
a I CONTROL l -C, the message 

■ S0RRY--PR0GRAM CAN'T BE STOPPED WITH 
CONTROL-C 

RESUME statement: see Section 3.5.2 is displayed on the screen (line 21520) and control is sent back to 

the point of the error with the R E S U M E statement in line 21530. 

If the error isn’t a I control | -C, the I F... T H E N test in line 21510 
sends control to line 215 5 0. Since the error routine has no special 
action to take for any of these other errors, and since Applesoft’s nor- 
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mal error messages are not being displayed, the error routine just 
displays a general error message such as 

UNANTICIPATED ERROR » CODE IG 

(for a syntax error) and stops the program. 

A 

Cover all the bases 

Warning 

Once anONERR GOTO statement has been executed, ordinary error 
messages will not be displayed and the program will not stop if an error 
is detected. If your program’s own error routine doesn’t take some ap¬ 
propriate action (such as stop) for every possible error code, the pro¬ 
gram may hang indefinitely or exhibit other forms of deviant behavior. 

Make sure your error routine tells the computer what to do in all possible 
cases of error; see the following box for suggestions. 

PEEK function : see Section 7.1.1 

More Peeking: In the program above, the general error message dis¬ 
played in line 21550 would be more useful if it included the line num¬ 
ber where the error occurred as well as the error code itself. Through the 
magic of the P E E K function, the following two lines (replacing line 

21550 of the original example) will do the trick: 

21550 EL = PEEK (219) * 25B + PEEK (218) 

—get error line 

21555 PRINT "UNANTICIPATED ERROR ^ CODE "5 

ECl "t IN LINE " 1 EL 

—display general error message 

For more information... 

For an even nicer way of handling unanticipated errors, see Section 

3.5.3, “Restoring Normal Error Handling.” See Appendix F, “Peeks, 

Pokes, and Calls,” for more astounding feats of sorcery and witchcraft 
you can perform at home. 

NoONERR GOTO in immediate 
execution 

The ONERR GOTO statement can be executed only from within a pro¬ 
gram; you can’t use this statement in immediate execution. 

3.5.2 

The RESUME Statement 

RESUME 

RESUME returns control from an 
error routine 

The RESUME statement returns control from an error-handling rou¬ 
tine to the statement in which the error occurred. It should be used 
only in error routines, and should never be encountered In the normal 
flow of control. 
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Warning 

If Applesoft encounters a R E S U M E statement without an error having 
occurred, the program may stop or hang indefinitely, or other unpredict¬ 
able but probably unpleasant events may transpire. 


A 


Warning 

Notice that RESUME sends control back to the same statement that 
caused the error in the first place. If the same error occurs again, the 
program may hang in an infinite loop. Similarly, if an error occurs within 
the error-handling routine itself, R E S U M E will cause the program to 
hang. 


Don’t leave a mess! 
control stack: see Section 3.4 


GOTO statement: see Section 3.1 


CALL statement: see Section 7.1.3 


Cleaning the Stack: When an error occurs while anONERR GOTO 
statement is in effect, Applesoft pushes certain information onto its inter¬ 
nal control stack before transferring control to the error routine. When 
you leave the error routine with a R E S U M E statement, these control 
codes are automatically popped off the stack. But if the error routine 
ends with a G 0 T 0 instead of a R E S U M E, the control codes will remain 
behind on the stack, probably causing the world to end with a whimper 
later on. To avert a global catastrophe, always “clean up” the stack by 
uttering the magical incantation 

CALL -3288 

before leaving an error routine with a G 0 T 0 statement. 


Don’t use RESUME in immed'ate 
execution! 


Warning 

The RESUME statement should be executed only from within a pro¬ 
gram. Attempting to use this statement in immediate execution may 
cause a syntax error, cause the system to hang, or begin executing an 
existing or even a deleted program. 


3.5.3 Restoring Normal Error Handling 

POKE 216 » 0 restores normal error You can restore Applesoft’s normal error-handling mechanism by 
handling using the P 0 K E statement: 


POKE statement: see Section 7.1.2 


POKE 216,0 


After executing this statement, Applesoft will go back to stopping the 
program when an error occurs and displaying its usual error 
messages. 


Error Handling 


71 










Apple lie Monitor program: see Apple 
He Reference Manual 


One use of this technique is to prevent your program from hanging or 
faiiing into the Monitor in qase an error occurs in the error-handiing 
routine itseif. You can do this by restoring normai error handiing with 
POKE 21B ♦ 0 at the beginning of your error routine, then reacti¬ 
vating the error routine with ONERR GOTO before returning to the 
main program. Here's another version of the exampie program of 
Section 3.5.1 that iiiustrates this technique: 

10 ONERR GOTO 21500 

—estabiish error routine at iine 
21500 


21500 POKE 21B>0 —restore normai error handiing 

21505 LET EC=PEEK (222) 

—get error code 

21510 IF EC <> 255 THEN 21540 

—if not I CONTROL | -C, resume 
program under normai error 
handling 

21520 PRINT "S0RRY--PR0GRAM CAN'T BE 
STOPPED WITH CONTROL-C" 

—if user pressed | control | -C, 
display special message, 

21530 ONERR GOTO 21500 

—reactivate this error routine, 

21540 RESUME —and resume program 

This program also illustrates another application of POKE 21B»0. 
Notice that if the error is anything other than a | control | -C interrupt 
(code 255), the I F...THEN test in line 21510 sends control di¬ 
rectly to the R E S U M E statement in line 215 4 0, without executing 
the ONERR GOTOinline 21530. The effect of this is to re-exe- 
cute the statement containing the original error, but with Applesoft’s 
normal error handling still in effect. This will cause the same error to 
occur again, but this time Applesoft will display its normal error mes¬ 
sage and halt the program. Thus I control | -C is the only error that 
gets special handling; all other errors produce the same results as if 
there were no special error routine. 
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3.6 

Program Termination 

The STOP and END statements are used to halt the execution of a 

debugging: finding and correcting errors 
in a program 

program. The only difference between them is that STOP displays a 
message giving the number of the line at which execution was halted; 
this information is useful primarily for debugging purposes. END sim¬ 
ply stops the program without any message, and is usually used at a 
program’s natural finishing point. 

3.6.1 

The STOP Statement 

STOP 

STOP halts the program and displays 
a message 

The STOP statement halts execution of the program and displays a 
message giving the number of the program line in which the S T 0 P 
occurs. For example, the line 

115 STOP 

displays the message 

BREAK IN 115 

CONT command: see Section 1.3.3 

Applesoft returns to its command level, allowing you to enter new 
lines, examine or change the values of variables, and so on. You can 
then resume the execution of the program using the C 0 N T 
command. 

3.6.2 

The END Statement 

END 

END halts execution quietly 

The END statement halts execution of the program and returns con¬ 
trol to Applesoft’s command level. No message is displayed on the 
screen; program execution just stops quietly. 

909 END 

END optional at end of program 

An E N D statement is purely optional at the end of a program. The pro¬ 
gram will end by itself, even without an E N D statement, when it runs out 
of statements to execute. 
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Chapter 4 


arrays: see Section 4.1 


strings: see Section 4.2 


4.1 

array: a collection of variables referred to 
by the same name 


element: one of the individual variables 
in an array 


simple variable: a variable that is not an 
element of an array 


Arrays and Strings 


This chapter discusses two important forms of data that Applesoft 
programs can operate on: arrays and strings. Both topics were 
treated briefly in Chapter 2, “Variables and Arithmetic,” but are cov¬ 
ered in more detail here. 

Section 4.1, “Arrays,” deals with collections of related information of 
any type (reai, integer, or string), referred to by the same name and 
distinguished by means of numerical subscripts. 

Section 4.2, “Strings,” describes Applesoft’s facilities for manipulat¬ 
ing strings of characters such as words or names: comparing them, 
concatenating (chaining) them together, taking them apart, and con¬ 
verting them to and from numeric values. 

Arrays 

An array is a collection of variables referred to by the same name, 
usually holding a collection of data items that are related to each 
other in some logical or systematic way. The individual variables in 
the array are called Its elements, and are distinguished from one an¬ 
other by means of identifying index numbers called subscripts. 

An array can be of any type: integer, real, or string. Array names fol¬ 
low the same rules as simple variable names of the same type. To re¬ 
fer to a particular element of an array, write the array name followed 
by one or more subscripts, separated by commas and enclosed in 
parentheses. The subscripts refer to the position of the desired ele¬ 
ment within the array: 

0 ( B ) —element G of real array 0 

FIGURE'^. (N) —element N of integer array 

FIGURED 


Arrays 


77 




NAME$ (J - 3) —element J - 3 of string 

array 

COUNT (SUMXt 2) —element (SUM% » 2) of real 

array COUNT 


Figure 4-1 A Real Array 


Array R 


^ R ( S ) 


^R (S + 2) 


R (0) 
R ( 1 ) 
R (2) ■ 

R (3) ■ 
R (4)- 


53 


27*35 


31 *4 


19 


Figure 4-1 shows a real array named R with five elements, numbered 
0 to 4. Element R ( 0 ) (pronounced “R-sub-zero”) holds the value 
5 3, R (1 ) holds 27.35, and so on. If the value of variable S is 2, 
then the expression R ( S ) refers to element R ( 2), whose value is 
31.4, and the expression R ( S + 2) refers to element R ( 4) , 
which holds the value 19. 

Another example is shown in Figure 4-2, this time a string array 
named N AME$ with seven elements, numbered 0 to B. Element 
NAHE$( 1 ) holds the string value "SCOT", NAME$ ( 3 ) holds 
the value "BRUCE", NAME$ ( B ) holds "MEG", and so on. Ifthe 
value of variable C 1 is 5, then the expression N A M E $ ( C % ) refers to 
element N A M E $ ( 5 ), whose value is " J . D . ", and the expression 
NAME$(CI - 3 ) refers to element NAME$ ( 2 ), which holds the 
value "BITZEL". 


Figure 4-2 A String Array 


Array NAME$ 

NAME$(0) 

NAME$ (1) ^ 

NAME$ (2) 

NAME$(3) ^ 

NAME$ (4) 

NAME$(5) ^ 

NAME$ (B) 


"BANA 


SCOT” 


“BITZEL" 


"BRUCE 


SUSAN" 


" J ♦ D ♦ " 


"MEG" 


NAME$ (C^ - 3) 


NAME$ iCl) 
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4.1.1 

The DIM Statement 


DIM R (4) 

DIM TITLE$ (100) 

DIM H5 (JI) 

DIM MARK! (3»C/5»P+2)* 

DIM defines the size of an array 

The DIM (for “dimension”) statement defines the size of an array 
and allocates memory space for its elements. The expressions in pa- 

dimension: the maximum size of one of 
the subscripts of an array 

rentheses following the array name give the dimensions of the array. 

There may be from one to 88 dimensions (see Section 4.1.2, “Multi¬ 
dimensional Arrays”). 

Once an array has been defined in a DIM statement, any reference 
to that array with a different number of subscripts, or with a subscript 
that exceeds the maximum specified for that dimension in the DIM 
statement, will cause the program to halt with the message 

?BAD SUBSCRIPT ERROR 

Available memory limits size of arrays 

Arrays are limited in size by the amount of available memory. See 

Section H.2, “Applesoft Memory Allocation,” for detailed information 
on the amount of space required by each type of array. 

Subscripts start from 0, not 1 

Since array subscripts in Applesoft begin with 0 (not 1), there is actually 
one more than the specified number of subscripts in each dimension. 

For instance, the array TIT L E $ defined in the second example above 
has 101 (not 100) elements. In the definition 

DIM TEST (12^ 3f 5) —array TEST has 13*4*6 = 

312 elements 

array TEST has312elements (13 times 4 times 6), not 180 (12times 3 
times 5) as you might expect. 


When Applesoft encounters a reference to an array that has not yet 
been defined in a DIM statement, it automatically allocates space for 11 
subscripts (0 to 10) in each dimension of the array. Later attempting to 
redefine the same array with a DIM statement will cause an error stop 
with the message 

?REDIM'D ARRAY ERROR 

Defining the same array In more than one DIM statement, or executing 
the same DIM statement twice, will produce the same message. 
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4.1.2 Multidimensional Arrays 

The examples shown in Figures 4-1 and 4-2 are both one-dimen¬ 
sional arrays. Actually, arrays in Applesoft may have as many as 88 
dimensions, subject to the amount of memory available. Arrays of 88 
dimensions aren’t terribly useful, but those of two and three dimen¬ 
sions often are. 

Figure 4-3a shows an example of a two-dimensional array named 
EGGS, which has been defined by the DIM statement 

DIH EGGS (1» 5) 


Figure 4-3a A two-dimensional array 


Array EGGS 


Column Column Column Column Column Column 
0 12 3 4 5 

Row 0 ^ 

Row 1 ^ 


o 

o 

(0^1) 

(0*2) 

iO* 3) 

iOf a) 

in 

o 

( 1 r 0 ) 

il f 1) 

il t2) 

il f3) 

il * a) 

( 1 f 5) 


For the newly perplexed, a metaphor may be helpful. Think of the 
array as an empty egg carton. On the outside is written the word 
EGGS. When you open the egg carton, there are a dozen cup-like in¬ 
dentations where the eggs go—two rows of six cups each—corre¬ 
sponding to the elements of the array. Each of the cups is identified 
Don’t forget subscript 0! by a row number, 0 or 1, and a column number from 0 to 5 (we’re 

dealing with strange chickens here). 

Now suppose you place three eggs in the egg carton, in elements 
(0 *2), (0 »5),and (1 >3): 

LET EGGS (Or 2) = EGG 

LET EGGS (Or 5) = EGG 

LET EGGS (1r 3) = EGG 


Figure 4-3b 


Array EGGS 



Column 

Column 

Column 

Column 

Column 

Column 


0 

1 


3 

4 


Row 0 



EGG 



EGG 

Row 1 




EGG 




Figure 4-3b shows the result. You might also elect to use your egg 
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carton to hold small change. If you put a nickel in position ( 0 »1), a 
dime in position (1 > 1), and a quarter in position (1 >4), 


Figure 4-3c 


Scrambled metaphor 


4.2 

String: a sequence of text characters 

String constants enclosed in double 
quotation marks 


Lowercase OK in string constants 


null string: a string containing no 
characters 


LET 

EGGS 

( 0 f 

1 ) 

= 5 

LET 

EGGS 

( 1 » 

1 ) 

= 10 

LET 

EGGS 

( 1 » 

4) 

= 25 


Array EGGS 



Column 

Column 

Column 

Column 

Column 

Column 


0 

1 

2 

3 

a 

5 

Row 0 ^ 


5 

EGG 



EGG 

Row 1 ^ 


10 


EGG 

25 



your carton would look like Figure 4-3c. 

Actually, of course, you can’t store eggs in your Applesoft arrays, only 
numbers and strings—but after all, metaphors aren’t always eggsact. 


Strings 

A string is a sequence of text characters (letters, digits, and punctua¬ 
tion marks). Just as you can write numeric constants such as 2 7 and 
2 4 2 3 G in your Applesoft programs, you can write string constants 
by enclosing the characters in the desired string between double 
quotation marks: 

"ON SALE FOR $49.95" 

"Truth is impe ryious to hissin S" 

"H2S04" 


Even though Applesoft doesn’t understand lowercase letters when you 
use them in keywords, it will allow you to use them in a string constant, 
as the second example above shows. 

A string can contain from 0 to 255 characters; when it contains no 
characters at all, it is called a nuli string. Two quotation marks with 
nothing between them denote the null string: 

"" —a string with no characters 
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string variable names end with $ 

String variables preset to null string 

4.2.1 

character code: a number used inside 
the computer to represent a text 
character 

ASCII: American Standard Code for In¬ 
formation Interchange; see Appendix C 


relational operators: see Section 2.3.2 


A string variable can hold any string as its value. Its name must end 
with a dollar sign ($). Some legal string variable names are 

TITLE$ 

G2$ 

D$ 

Until they are given some other value with an assignment statement, 
all string variables are preset to the null string. 


Comparison of Strings: The ASCii Code 

The characters in a string are represented inside the computer in the 
form of numbers from 0 to 127. The correspondence between 
these internal character codes and the characters they represent 
is based on a nationwide computer-industry standard called the 
American Standard Code for Information Interchange, or ASCII 
(pronounced “asky”). For instance, ASCII code B 5 represents the 
uppercase letter A, 112 represents a lowercase p, 5 2 represents 
the digit 4, 43 represents a plus sign (-t-), and soon. For a complete 
table of ASCII character codes and the characters they represent, 
see Appendix C, “ASCII Character Codes.” 

Like numbers, strings can be compared with each other using the re¬ 
lational operators. The result of the comparison is based on the II 
codes of the characters in the strings. Applesoft looks for the first 
non-identical characters in the two strings and compares them by 
ASCII code to decide which is greater. For example, the character F 
(ASCII 70) is considered greater than the character D (ASCII B8) 
but less than the character H (ASCII 72). If one string is longer but 
begins with all the same characters as the other string, the longer 
string is considered greater. For example. 


A" 

is less than 

"B" 

AA" 

is less than 

"AB" 

AB" 

is less than 

"BA" 

AB" 

is less than 

"ABC 
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string comparisons can be used for con¬ 
ventional alphabetical order... 


... but watch out! 


M A L function : see Section 4.2.5 

4.2.2 

L E N gives length of a string 
concatenation: see Section 4.2.3 


Since letters of the alphabet are represented by consecutive codes in 
the ASCII table, comparisons between strings of alphabetic letters can 
be used to place the strings in conventional alphabetical order. For 


example, 

»E'' 

Is less than 

H p M 

"ED“ 

is less than 

“EDGAR” 

^*EDGAR" 

is less than 

“EDWARD” 

“EDWARD” 

is less than 

“EDWARDS” 

“EDWARD” 

Is less than 

“FRANK” 

There are a few surprises, however: since uppercase letters precede 

lowercase letters In the ASCII chart, 

“Zebra” Is less than 

“aarduarK” 

And since strings are compared strictly character by character, 

CO 

Is less than 

“5“ 


If you want to compare two strings consisting of digits according to the 
numbers they represent, use the M AL function. 


The LEN Function 

The LEN (for “length”) function counts the number of characters in a 
string. The argument may be a string constant, a string variable, or a 
concatenation of two or more strings. For example. 


LEN 

( "APPLE") 

—length of the string 
"APPLE":yields5 

LEN 

(SAMPLE$) 

—length of the string contained 
in variable SAM PLE$ 

LEN 

(A$ -f "***" 

+ B$) 


—length of the concatenation of 
variable A $, string "***", 
and variable B $ 


Using L E N, you can assign the length of a string to a numeric vari¬ 
able and then use it in further operations: 


10 LET NX - LEN ("MY 
HAWK.") 

20 PRINT "THERE ARE ' 
IN THE STRING." 


HEART SOARS LIKE A 
; NX; " CHARACTERS 
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When executed, this program will display the following output on the 
screen: 

THERE ARE 27 CHARACTERS IN THE STRING* 

If you concatenate two or more strings with a combined length of more 
than 255 (the maximum allowable string length), your program will halt 
with the message 

?STRING TOO LONG ERROR 
Instead of writing 
LEN CA$ 4- 0$ + C$) 
it’s safer to use 

LEN (A$) + LEN (B$) + LEN (C$) 


4.2.3 Concatenation of Strings 

concatenate: to combine two or more Concatenation means “chaining together.” To concatenate two or 

strings intoasingie, longer string more Strings is to join them together into a new string containing all 

the characters of the original strings combined. This operation is rep¬ 
resented in Applesoft by a plus sign (-I-): 


L E F T $ function: see Section 4.2.4 


"BORIS" -I- " AND " + 

F$ -F C$ 

H$ -F "RATS!" 

H$ -F LEFT$(C$» a) 


"NATASHA" 

—concatenation of the strings 
"BORIS"," AND ",and 
"NATASHA":yieldsthe 
string "BORIS AND 
NATASHA" 

—concatenation of the contents 
of string variables F $ and C$ 

—concatenation of the contents 
of string variable H $ with the 
string constant "RATS I " 

—concatenation of the contents 
of string variable H$ with the 
leftmost four digits of the con¬ 
tents of string variable C $ 
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The program 



Result must not exceed 255 characters 


LEN function: see Section 4.2.2 


10 LET NAME$ = "CHARLIE" 

—set victim’s name 

20 LET TITLED = "DEAR " + NAriE$ + "» 

—form salutation 

30 PRINT TITLE$ —print salutation 

40 PRINT "HAOE WE GOT A SALE!" 

—print rest of message 


will display the output 


DEAR CHARLIE ♦ 
NAME WE GOT A 

SALE} 


on the screen. The program 

10 LET A$ = "GOOD 

" —assign value to string variable 

20 LET A$ = 

A$ + 

"GRIEF!" 

30 PRINT A$ 

will display 


—extend string with 
concatenation 
—display result 

GOOD GRIEF! 




If the result of a concatenation operation is a string more than 255 
characters in length, the program will halt with the error message 

7STRING TOO LONG ERROR 


You can test how long the result of a concatenation will be before¬ 
hand by using the LEN function. For example: 


10 

20 

30 

40 

50 


LET 

A$ 

= 

"HAPPY DAYS " 

LET 

LI 


LEN 

( A $ ) —how many characters in A $ ? 

LET 

B$ 

= 

"ARE 

HERE AGAIN" 

LET 

L2 

= 

LEN 

( B $ ) —how many characters in B $ ? 

IF 

(LI 


L2) 

< 256 THEN LET A$ = 

A$ + 



—if the combined lengths of A $ 


and B $ are less than 256, 
combine the two strings into 
A$ 
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+ on strings doesn’t mean addition! 


UAL function: see Section 4.2.5 


4.2.4 

substring: a string that is part of another 
string 


L E F T $ extracts a substring from the 
beginning of a string 


Real arguments converted to integers 


Don’t confuse the concatenation of strings with the addition of numbers, 
even though both are represented in Applesoft by the same symbol 
(+). The value of the expression 

12 + 34 

is the number 46; the value of the expression 
”12“ + "34" 

is the string " 12 3 4". If you want to add two strings consisting of digits 
according to the numbers they represent, use the UAL function. 


Substring Functions 

Applesoft has three built-in functions for extracting substrings from a 
string: 

• L E F T $ extracts a substring from the beginning of a string. 

• MID $ extracts a substring from anywhere in a string. 

• RIG H T $ extracts a substring from the end of a string. 

The LEFT$ Function 

L E F T $ extracts a specified number of characters from the begin¬ 
ning (left end) of a string. The L E F T $ function takes two arguments, 
separated by a comma: the string from which the characters are to be 
taken and the number of characters desired. For exampie, 

LEFT$ ("THIS IS IT!"» 4) 

—first 4 characters of the string 
"THIS IS IT!":yields 
"THIS" 

LEFT$ (NAME$» C -h 2) —first C 2 characters of 

the contents of string variabie 
NAME$ 

If the value you give for the number of characters in the substring is a 
real number, L E F T $ truncates it to the next lowest integer. If the 
value specified is greater than the length of the string, Applesoft re¬ 
turns the entire string: no extra characters are added. 

The number of characters requested must be between 1 and 2 5 5 or 
the program will halt with the message 

7ILLEGAL QUANTITY ERROR 


86 


Arrays and Strings 








MI D$ extracts a substring from any¬ 
where in a string 


j -- . 

c 

Third argument optional 


If you omit the dollar sign ($) from the function name LEFT$, Applesoft 
will treat L E F T as an arithmetic variable name, causing an error stop 
with the message 

?TYPE MISMATCH ERROR 


The MID$ Function 

MID $ (for “middle”) extracts a specified number of characters from 
a specified position within a string. The MI D$ function takes three 
arguments, separated by commas: the string from which the charac¬ 
ters are to be taken, the position within the string of the first character, 
and the number of characters desired. For example, 

MID$ ("HOW DO I LOME THEE?"» 10» 4) 

—4 characters beginning at po¬ 
sition 10 in string "HOW DO 
r I LOME THEE?";yields 

"LOME" 

MID$ (H9$* R -f 7» 2 * M) 

—2 * M characters beginning 
at position R + 7 in the 
contents of string variable 
H9$ 


You may optionally leave out the third argument to MID $. If you don’t 
specify the number of characters you want, or if the number of char¬ 
acters you request is greater than the length of the string, MID $ 
yields all characters from the designated starting position to the end 
of the string: 


MID$ ( "THERE THEY GO! " » 7) 

— all characters from position 7 
to end of string "THERE 
THEY G0!":yields 
"THEY GO!" 


MID$ (A$» 10) 


— all characters from position 10 
to end of the contents of string 
variable A$ 


MID$ ("HI THERE" 


20 ) 

— all characters from position 
4 to end of string "HI 
THERE";yields "THERE" 
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Real arguments converted to integers 


null string: a string containing no 
characters 


RIG HI $ extracts a substring from 
the end of a string 


Real arguments converted to integers 


If the value you give for the starting position or the number of charac¬ 
ters in the substring is a reai number, HID $ truncates it to the next 
iowest integer. If the designated starting point is greater than the 
length of the string, or if the number of characters requested is 0, 

MID $ yields the null string. 

The starting position must be between 1 and 255, and the number of 
characters between 0 and 255, or the program will halt with the 
message 

7ILLEGAL QUANTITY ERROR 

If you omit the dollar sign ($) from the function name MI D$, Applesoft 
will treat MID as an arithmetic variable name, causing an error stop with 
the message 

7TYPE MISMATCH ERROR 


The RI QHJi Function 

RIG H T $ extracts a specified number of characters from the end 
(right end) of a string. The RIG H T $ function takes two arguments, 
separated by a comma: the string from which the characters are to be 
taken and the number of characters desired. For exampie, 

RIGHT$ ("GIMME A BREAK"j 7) 

—iast 7 characters of the string 
"GIMME A BREAK"; 
yields "A BREAK" 

RIGHT$ (NAME$» C -K 2) 

— last C -h 2 characters of 
the contents of string variabie 
NAME$ 

if the vaiue you give for the number of characters in the substring is a 
reai number, RIG H T $ truncates it to the next iowest integer. If the 
value specified is greater than the iength of the string, Appiesoft re¬ 
turns the entire string; no extra characters are added. 

The number of characters requested must be between 1 and 2 5 5 or 
the program will halt with the message 

7ILLEGAL QUANTITY ERROR 

If you omit the dollar sign ($) from the function nameRIGHTf, Apple¬ 
soft will treat RIG H T as an arithmetic variable name, causing an error 
stop with the message 

?TYPE MISMATCH ERROR 
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ASCII code: see Section 4.2.1 


SIR $ converts a number to a string 


string Conversion Functions 

Strings and numbers are not the same, even when the string looks 
like a number: 

2 * 123 —yields 24G 

2 * "123" —TYPE HISMATCHerror 

LEFT$ ("123" » 2) —yields "12" 

LEFT$ (123j 2) —TYPE HISMATCHerror 

This section describes Applesoft’s built-in functions for converting 
between numeric and string values: 

• S T R $ converts a number to a corresponding string. 

• M A L converts a string to a corresponding number. 

• C H R $ converts an ASCI I code to the corresponding character. 

• A S C converts a character to the corresponding ASCII code. 


The STR$ Function 

The S T R $ (for “string”) function converts a numeric value into a 
string representing that value. For example, 


STR$ 

(-100) 

— a string representing the num¬ 
ber - 100; yields " - 100 " 

STR$ 

(3.14159) 

— a string representing the num¬ 
ber 3. 14153; yields 
"3,14159" 

STR$ 

(MARK) 

— a string representing the nu¬ 
meric value of real variable 
MARK 

STRf 

(COUNT';?.) 

— a string representing the nu¬ 
meric value of integer variable 
COUNT’Z 

STR$ 

(B"2 - 4*A*C) 

— a string representing the nu¬ 
meric value of the expression 


B'-2 - a*A*C 
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M A L converts a string to a number 


RI GHT$ function: see Section 4.2.4 


The string produced by S T R $ is in the same format that Applesoft 
uses to display or print numbers; see Appendix I, “Display Formats 
for Numbers,” for details. For example, 


STR$ 

(100 000 

000) 

— yields " 10 0 0 0 0 0 0 0" 

GTRf 

( 1 000 0( 

)0 000) 

— yields " lE + 09" 

STR$ 

(-.03) 


— yields " - .03" 

STR$ 

(-.003) 


— yields "-3E-03" 


If the numeric value of the argument falls outside the allowable 
range for real numbers (-9.99099999E + 37to 
+ 9.99999993E + 37),the program will halt with the message 

TOMERFLOW ERROR 

The MAL Function 

The MAL (for “value”) function converts a string to the numeric value 
It represents. For example, 

MAL CaOSB") 

MAL ("-1.505E + 2" ) 

MAL (WHOLE$ + + 

MAL ( RIGHT$ (Q$» 4) 


— number represented by the 
string " 4 0 9 G "; yields 4 0 9 G 

— number represented by the 
string "-1.505E + 2"; 
yields -150.5 

FRAC$) 

— number represented by the 
concatenation of strings 
WH0LE$, ■' . ",andFRAC$ 

) 

— number represented by the 
last 4 characters of string 0 $ 
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!"*.**‘-W* _, 


UAL recognizes same number formats 
as INPUT;seeSection5.1.2 


UAL recognizes the same number formats that can be used in key¬ 
board input; see “Rules for Numeric Input” in Section 5.1.2, “The 
INPUT Statement.” If M A L encounters a non-numeric character in 
its argument string, it yields the numeric value of everything up to the 
first non-numeric character, ignoring the rest of the string. (The digits 
0 through 9, the signs + and -, the decimal point (.), and the letter 
E for scientific notation are considered numeric characters. Spaces 
are also allowed, and are simply ignored.) If the first character in the 
string is non-numeric, UAL yields a value of 0. For example. 


UAL ("12.54 OR SO") —yields 12.54 
UAL ("ABOUT 4.57") —yields 0 


If the absolute value of M A L’s result is greater than 1E 3 8 or contains 
more than 38 digits (including trailing zeros), the program will halt with 
the message 


TOUERFLOW ERROR 


The Ci-IR$ Function 

CHR$ converts an ASCII code to the The CHR$ (for “character”) function regards its single numeric ar- 

corresponding character gument as an ASCII character code and yields a one-character 

string consisting of the corresponding character. For example. 


ASCII code: see Section 4.2.1 antd 
Appendix C 

CHR$ 

(68) 

— character with ASCII code 

8 8 ; yields the string " D " 


CHR$ 

(47) 

—character with ASCII code 47; 
yields the string " / " 


CHR$ 

(7) 

—character with ASCII code 7; 


yields a string containing 
the ASCII bell character 


( I CONTROL | -G) 

CHR$ (Cl) —characterwhose ASCII code 

is the value of variable C1 

CHR$ (LI + B4) —character whose ASCII code 

is the value of expression 
LI + G4 

Real arguments converted to integers If the value of the argument is a real number, C H R $ truncates it to the 

next lowest integer. For example, 

C H R $ (81.0) —argument truncated to 81; 

yields " 0" 
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An argument less than 0 or greater than 255 will cause the program to 
halt with the message 

7ILLEGAL QUANTITY ERROR 


A S C converts a character to the 
corresponding ASCII code 

ASCII code: see Section 4.2.1 and 
Appendix C 


MID $ function: see Section 4.2.4 


null string: a string containing no 
characters 


The ASC Function 

The ASC (for “ASCII”) function takes a single string argument and 
yields the ASCII code corresponding to the first character in the 
string. For example, 


ASC ("D") 

ASC ("/") 

ASC ("e» e. c ufiuti i n ^ s " 

ASC (B0$) 

ASC ( HID$ (NAME$r 5) 


—ASCI I code for character D; 
yields 6 8 

—ASCII code for character /; 
yields 4 7 

) 

—ASCI I code for character e; 
yields 101 

—ASCII code for the first charac¬ 
ter in string B0$ 

) 

—ASCI I code for the fifth charac¬ 
ter in string NAHE$ 


If the argument given to A S C is the null string, the program will halt with 
the message 

7ILLEGAL QUANTITY ERROR 
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Chapters 


input: see Section 5.1 

output: see Section 5.2 


input: the transfer of information into the 
computer from an external source 

IN# statement: see Section 5.1.1 

INPUT statement: see Section 5.1.2 

GET statement: see Section 5.1.3 

READ statement: see Section 5.1.4 

DATA statement: see Section 5.1.4 

RESTORE statement: see Section 
5.1.5 

miscellaneous input: see Section 5.1.6 


input/Ou^ut 


This chapter is concerned with the ways in which Appiesoft programs 
communicate with the outside world. Here are described Applesoft’s 
facilities for getting information into and out of the computer and for 
controlling the way information is presented. 

Section 5.1, “Input,” deals with the various statements through which 
Applesoft programs receive information for processing. 

Section 5.2, “Output,” describes how programs transfer information 
to the “outside world”: to the display screen, printers, and so forth. 

Input 

The input statements discussed in this section enable Applesoft pro¬ 
grams to receive information for processing, either from the keyboard 
or from a peripheral device connected to the computer via one of the 
expansion slots: 

• The IN # statement controls the source from which the com¬ 
puter receives its input. 

• The INPUT statement accepts a line of input from the current 
input device. 

• The GET statement reads a single character from the current in¬ 
put device. 

• The READ, DAT A, and RESTORE statements are used to read 
information from within the running program itself. 

• A few miscellaneous input facilities are available for reading the 
hand controls and for reading information from a cassette tape 
recorder. 
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5.1.1 The IN# Statement 

IN# 2 
IN# X 

IN# SLOT - J 


IN# specifies source for subsequent The IN# statement specifies the source from which the computer 

'"P"* will receive subsequent input. The expression following the keyword 

IN# should evaluate to a number between 0 and 7, designating the 

expansion slot: see Apple lie Owner’s expansion siot from which input is to be taken. 

Manual and Apple He Reference Manual 


When Applesoft is started up, it is set to receive input from the 
keyboard. Executing an IN# statement with a slot number from 1 
to 7 instructs Applesoft to receive input instead from the peripheral 
input device (such as a terminal or modem) connected to the 
Slot number 0 specifies input from designated siot. A slot number of 0 reestablishes the keyboard as 
keyboard current input device. For example, the following program 

fragment reads a single character from the device connected to 
slot 2, then reestablishes keyboard input: 



510 

IN# 

*7 

—accept input from device in 
slot 2 

GET statement: see Section 5,1.3 

520 

GET 

A$ 

—read one character from 
device in slot 2 


530 

IN# 

0 

—accept future input from 
keyboard 


Notice that the character # is part of the keyword IN# and cannot 
be omitted. 

Restarting the System with IN#: If the slot designated in an IN# or 
PR# statement: see Section 5.2.1 PR# statement contains a disk controller card, Applesoft will attempt to 

restart (often called “booting”) the system from the disk contained in 
drive 1 connected to that slot. When you do this on purpose, it’s the 
usual way of restarting the system from within Applesoft; when you do it 
Be careful! by mistake, it can be a catastrophe. 



I CONTROL I - 1 reset] : see Section 1.3.2 


Warning 

If no input device is connected to the slot designated in an IN# state¬ 
ment, the system will hang. To recover, use | control | - | reset | . 

A slot number between 8 and 2 5 5 will cause unpredictable and possi¬ 
bly aberrant behavior. 
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INPUT reads a line of input 
current input device: see Section 5.1.1 

prompt: to remind or signal the user that 
some action is expected 


current output device: see Section 
5.2.1 


Prompting message optional 


A slot number less than 0 or greater than 255 will stop the program 
with the message 

?ILLEGAL QUANTITY ERROR 


The INPUT Statement 

INPUT PRICE 

INPUT MNTHZ» DAY%# YEARX 
INPUT "WHAT IS YOUR PASSWORD? "5 
PASSWD$ 

INPUT K 


The INPUT statement accepts a line of input (terminated by 
I RETURN I ) from the current input device, containing vaiues to be as¬ 
signed to one or more variables. The variables to be read are listed in 
the IN PUT statement, separated by commas. 


The INPUT statement may optionally include a message to be dis¬ 
played or printed on the current output device, prompting the user for 
the desired input. If present, the prompting message must be given 
as a string constant immediately following the keyword INPUT and 
followed by a semicolon to separate it from the list of variable names. 
The specified prompting string is reproduced exactly as written; if 
displayed on the screen, it is immediately followed on the same line 
by the cursor. If the prompting message is omitted from the INPUT 
statement, a question mark (?) is used; the question mark can be 
suppressed by supplying a null string as the prompting message. For 
example. 


10 

20 

30 


40 


50 


PRINT "WHAT IS YOUR AGE» PLEASE?" 

—display prompting message on 
its own line 

INPUT AGE —prompt with ? and wait for 

response 

INPUT "YOUR STREET NAHE? "! ST$ 

—display prompting message on 
same line as cursor and wait 
for response 

PRINT "PLEASE TYPE YOUR FIRST AND 
LAST NAMES> SEPARATED BY A COMMA:" 

—display prompting message on 
its own line 

INPUT ""5 FN$ > LN$—suppress ? and wait for two 

responses separated by a 
comma 
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Colon causes remainder of line to be 
ignored 


I CQNTRQL~1 -C: see Section 1.3.2 


Length of input line limited 


No IN P U T in immediate execution 


The INPUT statement in line 2 0 above displays a question mark to 
prompt the user for input, followed by the cursor. The INPUT state¬ 
ment in line 3 0 displays the prompting message YOUR STREET 
NAME? instead of the question mark, again followed by the cursor. 
The INPUT statement in line 5 0 displays the cursor only, with no 
question mark and no prompting message of any kind. 

If the user types a colon (;) as part of an input l ine, the rem ainder of that 
input line is ignored. The ASCII null character ( | control | -C) has the 
same effect. 


An IN P UT statement can be interrupted by | control | -C, but only if it 
is the first character typed on an input line. The program halts when the 
I RETURN I key Is pressed at the end of that line. A | control | -C that is 
not the first character of the input line is treated as part of the input, the 
same as any other character. 


Be sure to give your users clear instructions about how long their re¬ 
sponses can be. If the user types an input line longer than 255 charac¬ 
ters, the whole line will be canceled and will have to be retyped from the 
beginning (the Apple I le’s speaker will beep from about the 245th char¬ 
acter, but no message will be displayed). A response of more than 239 
but fewer than 255 characters will be truncated to 239 characters with no 
warning message displayed. 


The INPUT statement can be executed only from within a program; 
you can’t use this statement in immediate execution. 

Multiple Inputs on the Same Line 

The INPUT statement may list any number of variables to be read 
from the same input line. The user’s responses to these variables 
must be separated by commas. You can mix string and numeric vari¬ 
ables in the same INPUT statement, but the user’s responses must 
each be of the correct type. 

If the user presses the | return | key (or types a colon or fcoNTROLl -g) 
without typing enough responses for all the variables listed in the 
INPUT statement, Applesoft displays two question marks to show 
that it expects a further response. If a colon, comma, or |coNTRDL| -i 
is the first character of a response, Applesoft interprets the response 
as zero or as the null string (depending on the type of variable speci¬ 
fied) and the program continues with the next statement. 
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Be kind to your users! 


Quotation marks optional 
Leading spaces ignored 

Rules for quoted responses 


If the user types more responses than Applesoft expects, or types a 
colon into the final expected response, Applesoft displays the 
message 

?EKTRA IGNORED 

and program execution continues. If the last response is shortened 
bya | CONTROL | -@—the program continues but no message is 
displayed. 

Programming Tip: Multiple inputs on the same line can be confusing 
for your users; it’s best not to use them except for “quick and dirty” test¬ 
ing purposes while you’re debugging your code. Instead of asking for 
something terribly unfriendly like 

PLEASE TYPE LAST NAME» FIRST NAME» MIDDLE 
INITIAL: 

use a form such as 

PLEASE TYPE YOUR FIRST NAME: 
followed by 

PLEASE TYPE YOUR MIDDLE INITIAL; 

JUST PRESS RETURN IF YOU HAVE NONE 

and so on. You’ll be able to give much clearer instructions, your user will 
have an easier time giving you what you want, and you’ll be better able to 
detect and deal with errors in the input. 

Rules for String Input 

The following rules govern the responses the user types to string 
variables in the IN PUT statement; 

• The user’s response to a string variable may be typed with or 
without enclosing quotation marks. 

• Applesoft ignores all spaces preceding the first nonspace 
character. 

• If the first nonspace character is a quotation mark, the input 
string is considered to include everything up to (but not including) 
the next quotation mark, | control | -g, or | return | . The string 
may include commas and colons, but may not include quotation 
marks, since these would be interpreted as marking the end of 
the string. Spaces following the closing quotation mark are ig¬ 
nored, but any other character causes the response to be re¬ 
jected with the message 

7REENTER 
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Rules for unquoted responses 


Null responses OK 


Control characters cause problems 


String expressions don’t work 


All spaces ignored 


• If the first nonspace character is not a quotation mark, the input 
string includes everything up to (but not including) the next 
comma, colon, | control | -@,or | return | . The string may in- 
ciude quotation marks, but may not include commas or colons, 
since these would be interpreted as marking the end of the string. 
Spaces following the last nonspace character are accepted as 
part of the input string. 

• If the first nonspace character is a comma, colon, | control | -@, 
or I RETURN I , the response is interpreted as the null string and 
program execution continues. 

• The following control characters cannot be included in the 
response: 

• I CONTROL I -H (equivalent to the | left-arroh | or backspace 
key) 

• I CONTROL | -M (equivalent to the I return | key) 

• I CONTROL | -K (cancels the input line) 

• I CONTROL | -@ (ASCII null character; causes remainder of in¬ 
put line to be ignored) 

In general, control characters cause problems and should not be 
used in responding to IN PUT statements. 

• The response to a string variable must be a single string or a con- 
stanti it cannot be a string expression involving concatenation, 
LEFt$,MID$,RIGHT$, or other string operations. Re¬ 
sponses such as 

A$ -I- B$ 

LEFT$ (HNTH$f 3) 

RIGHT$ (NAME$» L - (FL + 2)) 

will be accepted exactly as typed, character for character (up to 
the first comma), and will not be evaluated as string expressions. 

RuIbs for Numeric Input 

Listed below are the rules governing the user’s responses to numeric 
variables. If a response is typed that doesn’t conform to these rules, 
Applesoft will display the message 

?REEI\1TER 

reissue the prompting message, and wait for another response. 

• Spaces are ignored in any position. 
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Numeric characters only 
scientific notation: see Section 1.2 


Form of numbers 


Degenerate cases interpreted as 0 


Null responses interpreted as 0 


Most control characters illegal 
Arithmetic expressions invalid 


• The response is considered to include all nonspace characters 
up to (but not including) the next comma, colon, | control | -@, or 

I RETURN I ■ 

• The response may include numeric characters and spaces only. 
Numeric characters include the digits 0 to 9, the signs + and -, 
the period (decimal point), and the letter E for scientific notation. 
A response containing a non-numeric character in any position is 
invalid. 

• Numeric responses consist of the following elements. Any or all 
of these elements may be omitted, except that the sign or value 
of the exponent may not appear unless preceded by the letter E. 
Those that are included must be given in the order listed: 

• A sign (4- or -) 

• One or more digits 

• A decimal point (.) 

• One or more digits 

• The letter E for scientific notation 

• A sign ( -I- or -) for the exponent 

• One or more digits 

Even forms such as -t- E - and . E are accepted, and are inter¬ 
preted as 0. 

• If the first nonspace character is a comma, colon, or | return | , 
the response is interpreted as 0 and program execution contin¬ 
ues. A response beginning with | control 1 -@ is invalid. 

• The following control characters have special meanings: 

• I CQNTRQL~| -H (equivalent to the | left-arroh | or backspace 
key) 

• I CONTROL I -M (equivalent to the | return | key) 

• I CONTROL I -K (cancels the input line) 

• I CONTROL | -@ (ASCII null character: causes remainder of in¬ 
put line to be ignored) 

A response containing any other control character, in any posi¬ 
tion, is invalid. 

• The response to a numeric variable must be a single number; it 
cannot be a numeric expression involving arithmetic operations 
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UAL function: see Section 4.2.5 


POKE statement: see Section 7.1.2 


or function calls. Responses such as 
1/2 

B-2 - a*A*C 
SOR (2) 

are invalid because of the non-numeric characters. 

It's a good idea to use string variables to accept all numeric inputs, using 
the y AL function to convert them to numeric values. This makes it eas¬ 
ier to detect and deal with user errors and to display alternate prompting 
messages. 

An “Input Anything” Routine 

The INPUT statement interprets the colon and the comma (and 
sometimes the quotation mark) as special symbols and rejects any¬ 
thing typed after them in the input line. Here’s a bit of magic you can 
use if you anticipate that your user’s response may include any of 
these characters. 

The following Applesoft subroutine uses the POKE statement to 
store a special machine-language routine into the computer’s mem¬ 
ory, one byte at a time, beginning at address 7 S 8. The machine-lan¬ 
guage routine will accept all characters in the input, including colons, 
commas, and quotation marks, without “censoring” them, and will 
assign them, character by character, to a string variable for further 
processing. (The line numbers used below are arbitrary: you can 
locate this subroutine anywhere you like in your program.) 

B2000 REM SET UP "INPUT ANYTHING" 

ROUTINE 

B2010 LET IN$ = "K" —I N$ must be first variable 

created 


B2020 

FOR J 

- 7BS 

TO 790 




—these are memory addresses 




where machine language is to 
be stored 

B2030 

READ 

I 

—get a byte of machine 




language 

B2oao 

POKE 

J * I 

—store it at next location 

B2050 

NEXT 

J 

— go back for next byte 

B20B0 

DATA 

1B2* 0* 

32* 117* 253* IBO* 2* 


138* las* 105* 200* IBS* 0* 145* 
105* 200* 1B0* 2* 145* 105* 7B* 

5 7 * 213 —these are the actual bytes of 

machine language 

B2070 RETURN —return to statement following 

point of call 
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CALL statement: see Section 7.1.3 


The DATA statement containing the machine language must be re¬ 
produced in your program exactly as shown. 

The following subroutine uses the CALL statement to call the ma¬ 
chine-language routine at address 7B8. (Again, this subroutine can 
be located anywhere in your Applesoft program, not necessarily at 
line numbers 3000.) 

REM CALL "INPUT ANYTHING" ROUTINE 
CALL 7 B 8 —call machine-language routine 

IN$ = MID$ (IN$» 1) 

— IN $ now holds the input that 
the machine-language routine 
accepted 

RETURN —return to statement following 

point of call 

To accept a line of input from the user, instead of using a statement 
such as 

100 INPUT S$ 
substitute this line: 

100 GOSUB G3000 : LET S$ = IN$ 

The variable S $ now contains whatever input the user typed, includ¬ 
ing the “forbidden” characters: your program can proceed to process 
the input in whatever way is appropriate. 

For technical reasons having to do with the way variables are stored in 
memory, the string variable used to pass the user’s response between 
machine language and Applesoft (arbitrarily called IN $ in the example 
above) must be the first variable used or defined in the program. To be 
safe, you might want to call the “input anything” setup routine from line 
number 0: 

0 GOSUB 62000 


G3000 

G3010 

G3020 


G3030 
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5.1 .3 The GET Statement 


GET reads a single input character 
current input device: see Section 5.1.1 


semicolon: see Section 5.2.2 


No G E T in immediate execution 

I CONTROL | -C won’t interrupt a GET 
I C0NTR0L~] -C : see Section 1.3.2 


GET L$ 

GET S$(N) 

GET Cl$» C2$» C3$ 


The GET statement reads a single character from the current input 
device. Although it can be used to read from any peripheral input de¬ 
vice (such as a terminal or modem), it is seldom used in actual prac¬ 
tice with anything other than the keyboard. 

GET accepts one character from the current input device for each of 
the string variables listed following the keyword GET. Each single 
character is read as soon as it is typed, without waiting for the user to 
press the | return I key. The character is not displayed on the 
screen, and the cursor is not moved in any way. 

Here’s an example of a program fragment using G E T: 

310 PRINT "PRESS THE 'Y' KEY TO GO ON:"; 

—prompt user for response 
(semicolon keeps cursor on 
same line) 

320 GET A$ —wait for user to press key 

330 IF A$ <> "Y" THEN 320 

—keep cycling until user presses 
correct key 

340 PRINT —move cursor to new line (can¬ 

cels effect of semicolon from 
line 310) 

350 PRINT "THANK YOU"—politeness from machines is 

always welcome 

The GET statement can be executed only from within a program; you 
can't use this statement in immediate execution. 


If typed in response to a GE T, | control | -C is treated like any other 
character: it does not interrupt program execution. 
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DOS: Disk Operating System 


MAL function: see Section 4.2.5 


READ reads information from body of 
program 

DATA sets up information for use by 

READ 



A DOS command issued immediately after a G E T will not be recog- 
nized. For DOS commands to be executed properly, you must Issue a 
1 RETURN I character immediately after the G EI and before the DOS 
command. An easy way to do this is with an empty PRINT statement: 

PRINT 

See your DOS manual for more information. 


Numeric inputs with GET: The GET statement is neither designed nor 
Intended to obtain values for numeric variables. You may attempt to do 
so at your own peril, subject to the following limitations: 

• A comma or a colon will result in the message 
TEKTRA IGNORED 

and will be interpreted as a numeric value of 0. 

• A plus sign, minus sign, [ control h ©, E, space, or period will be 
interpreted as a numeric value of 0. 

• Any non-numeric character will cause the program to halt with a 
syntax error. 

It’s better to use only string variables with the G E T statement, using the 
M A L function to convert the response to a numeric value. 


The READ and DATA Statements 

READ PRICE 

READ A» J%> S$(2*J - 1)» T$ 

DATA 12.0» HI HO. 1B8 
DATA 2.23G 


The READ and DATA statements are used to read information from 
within the body of the Applesoft program itself, rather than from the 
keyboard or an input device. There may be any number of D A T A 
statements in a program, each containing a list of one or more items 
of information (numbers or strings) following the keyword DATA and 
separated by commas. All of the DAT A statements in the program 
are considered to form one long list of items, in sequential order of 
line numbers; each READ statement reads one or more items from 
this list. 
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RESTORE statement: see Section 
5.1.5 

Don’t read past end of list! 


Rules for numeric and string input: 

see Section 5.1.2 


DATA statements may appear 
anywhere 


Each time it executes a R E A D statement, Applesoft remembers the 
last item read from the D A T A list. The next READ always begins 
with the next item in the list. There is no way to “back up” or “skip for¬ 
ward” in the D A T A list, but you can start over from the beginning of 
the list with the R E S T 0 R E statement. 

An attempt to read past the end of the D A T A list will halt the program 
with a message such as 

TOUT OF DATA ERROR IN 14G5 

identifying the line number of the R E A D statement in which the error oc¬ 
curred. Leaving part of the DAT A list unread at the end of the program 
does not cause an error. 

The items in a D A T A statement are separated by commas and follow 
the usual rules for numeric and string input, except that a D A T A 
statement cannot contain a colon (s )■ The number of items in each 
DATA statement is limited only by the length of the program line. A 
DATA statement may appear anywhere in your program; it need not 
precede the R E A D statement that uses it. There is no limit to the 
number of D A T A statements in a program. 

Here’s an example program showing the use of the R E A D and 
DATA statements; 

10 DATA "GO WEST* YOUNG MAN" 

—item containing a comma; OK 
between quotation marks 
SAM" 

—mixed types in same DATA 
statement 

—read GO WEST* YOUNG 
M A N into string variable A $ 
and 3 « 1415S into real vari¬ 
able B; notice that these items 
come from two different 
DATA statements 
—read 2 into integer variable C'/f., 
SAM into string variable D $, 
andTHE "WORLD" IS 
FLAT into string variable E $; 
begins with next item following 
previous READ statement 


20 DATA 3,14159 * 2 * 

30 READ A$* B 

40 READ Cl* D$* E$ 
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Null items interpreted as 0 or null string 


A L function ; see Section 4.2.5 


Most control characters treated as 
ordinary characters 

I CONTROL | -C:see Section 1.3.2 


50 DATA THE "WORLD 


BO 

PRINT 

E$ 

70 

PRINT 

A$ 

80 

DATA 

CD 

CO 

30 

END 



IS FLAT 

—item containing quotation 
marks; notice that this item fol¬ 
lows the R E A D statement that 
uses it 

—displayTHE "WORLD" 

IS FLAT 

—display GO WEST * 

YOUNG MAN 
273.IB 

—these items never read 


Null items in a DATA statement are interpreted as 0 or the null 
string, depending on the type of variable to which they are assigned 
in a RE AD statement. A null item is read whenever there are no non¬ 
space characters 

• between the keyword DATA and the end of the program line 

• between the keyword DATA and the first comma 

• between two consecutive commas 

• between the last comma and the end of the program line 

Thus the statement 


DATA » » 


contains three null items. 

An attempt to read a string value in a D A T A statement with a numeric 
variable in a R E A D statement causes a syntax error. Numeric values 
can be read into string variables, but must be evaluated with the UAL 
function before they can be used as numbers. 


The charac ters | control | -H, | control t -M, | control | -X, and 
I CONTROL I -i cannot be embedded in a DAT A statement. Any other 
control character typed into a D A T A statement is treated as an 
ordinary character and becomes part of the input. A | control j -C 
character in a D A T A statement will not Interrupt the program. 


The READ statement can be executed only from within a program; you 
can’t use this statement in immediate execution. 
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5.1.5 r/je RESTORE Statement 

RESTORE 


RESTORE restarts DATA list The RESTORE Statement restarts the DAT A list from the beginning. 

After RESTORE is executed, the next READ statement will read the 
first item in the first DATA statement in the program. For example, 


10 DATA "GO WEST» YOUNG HAN" 


20 

30 

DATA 

READ 

3.14 
A$ » 

153 » 2 ♦ 
B 

40 

READ 

Cl f 

D$ » E$ 

50 

GO 

DATA 

PRINT 

THE 

E$ 

"WORLD" 

70 

80 

RESTORE 
READ 0$ 


90 

PRINT 

0$ 


100 

PRINT 

A$ 


no 

120 

END 

DATA 

38.G 

. 37» - 


"SAH" 

—read GO WEST* YOUNG 
HAN into string variable A $ 
and 3.14153 into real vari¬ 
able 5 

—read 2 into integer variable CX, 
S A H into string variable D $, 
and THE "WORLD" IS 
FLAT into string variable E $ 
IS FLAT 

—displayTHE "WORLD" 

IS FLAT 

—restart list from beginning 
—read GO WEST » YOUNG 
HAN into string variable 0 $ 

—display GO WEST > 

YOUNG HAN 
—display GO WEST » 

YOUNG HAN(valueofA$ 
still Intact) 

273.IG 

—these items never read 


There is no easy way to reposition the D A T A list to a specific desired 
item or line number. The only other Applesoft statement that affects 
the positioning of the DATA list is RUN, which also restarts the list 
from the beginning. 
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P D L reads dials on hand controls 


Standard hand controls numbered 0 
and 1 


Result of PDL is between 0 and 255 


Miscellaneous Input Facilities 

This section covers Applesoft’s facilities for dealing with the remain¬ 
ing input features of the Apple Me: the hand controls and cassette 
tape input. 

The Hand Controls 

If you have a set of hand controls connected to your computer, you 
can use the PDL function to read their dial settings. The Apple lie 
can accommodate as many as four hand controls, numbered 0 to 3, 
connected through the 9-pin hand control connector on the comput¬ 
er’s back panel or the GAME I/O connector inside the case on the 
main logic board. However, the standard Apple hand control set con¬ 
sists of only two controls, numbered 0 and 1. 

The PDL function takes one argument, the number of the hand con¬ 
trol to be read, and yields an integer from 0 to 2 5 5 representing the 
current position of the dial on that control. For example. 


10 

LET K = 

PDL 

(0) 

20 

LET P7„ = 

X * 

40 

30 

HTAB P’;' 



40 

PRINT "< 

ii 


50 

LET Y = 

PDL 

( 1 ) 

BO 

LET = 

Y * 

40 

70 

HTAB Q1 



80 

PRINT “> 

ii 


90 

IF K = 0 

AND 

Y 

100 

GOTO 10 




—read hand control 0 
/ 25B-I-1 

—reduce to a number from 1 to 

ao 

—move cursor to indicated posi¬ 
tion on current line 
—display the character < 

—read hand control 1 
/ 25B-I-1 

—reduce to a number from 1 to 
40 

—move cursor to indicated posi¬ 
tion on current line 
—display the character > 

= 0 THEN END 
—end program when both hand 
controls read 0 

—otherwise repeat the process 


If the argument given to P D L is less than 0 or greater than 2 5 5, the 
program will halt with the message 

?ILLEGAL QUANTITY ERROR 

If the argument is between 4 and 2 5 5, or if no hand control of the desig¬ 
nated number is connected, the results are unpredictable. 
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Allow a delay between calls to P D L 


If your program reads two hand controls in consecutive statements, the 
reading from the first hand control may affect the reading from the sec¬ 
ond. To obtain more accurate readings, allow several program lines be¬ 
tween calls to P D L or use a short delay loop such as 

FOR X = 1 TO 10 : NEXT X 

between PDL calls. 


Historical Note: The function name PDL stands for “paddle,” which in 
turn is short for “game paddle,” an older name for the Apple lie’s hand 
controls. 


Reading the hand control buttons The buttons on the hand controls can be read with the function calls 


PEEK function : see Section 7.1.1 

PEEK 

(-1B287) 

—yields a value > 12 7 if button 
on hand control 0 is being 
pressed, < = 12 7 if not 


PEEK 

(-1B28B) 

—yields a value > 12 7 if button 
on hand control 1 is being 
pressed, < = 12 7 if not 


PEEK 

(-1B285) 

—yields a value > 12 7 if button 
on hand control 2 is being 
pressed, <= 127 if not 


There is no way to read the button on hand control 3. The P E E K calls 
listed above are also used to read the “apple keys” on the Apple Me 
keyboard: the | open-apple | key is equivalent to the button on hand 
control 0, and | solid-apple | is equivalent to the button on hand 
control 1. 

For more information... See the Apple Me Reference Manual for detailed technical information 

on the 9-pin hand control connector and the internal GAME I/O 
connector. 

Cassette Input 

Three Applesoft statements, LOAD, RECALL, and SHLOAD, can 
be used to read information from a cassette tape recorder. LOAD 
reads an Applesoft program into memory from tape; RECALL reads 
the contents of an integer or real array; SHLOAD reads a shape ta¬ 
ble for use in high-resolution graphics. For details, see Appendix M, 
“If You Have a Cassette Recorder.” 


LOAD command: see Section 1.2.6 and 
Appendix M 

RECALL statement: see Appendix M 

SHLOAD statement: see Section 6.3.2 
and Appendix M 
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5.2 

output: the transfer of information from 
the computer to an external destination 

PR# statement: see Section 5.2.1 


PRINT statement: see Section 5.2.2 


number formats: see Section 5.2.3 


screen formatting: see Section 5.2.4 


miscellaneous output: see Section 
5.2.5 


5.2.1 


PR# specifies destination for subse¬ 
quent output 

expansion slot: see Apple He Owner’s 
Manual and Apple He Reference Manual 


Slot number 0 specifies output to the 
screen 


Output 

This section describes the output facilities available in Applesoft: 

• Section5.2.1 coversthe PR# statement, which controls the des¬ 
tination to which output is directed. 

• Section 5.2.2 contains a detailed discussion of the P RIN T 
statement, Applesoft’s primary output statement. 

• Section 5.2.3 gives details on the way numbers are formatted 
when written with the PR I NT statement. 

• Section 5.2.4 describes Applesoft’s wide variety of facilities for 
controlling the format in which textual information is displayed on 
the screen. 

• Section 5.2.5 touches briefly on various miscellaneous output fa¬ 
cilities not covered elsewhere: the Apple lie’s built-in speaker, 
annunciator outputs, utility strobe, and cassette tape output. 


The PR# Statement 

PR# 1 
PR# K 

PR# SLOT - J 


The PR# statement specifies the destination to which the computer 
will send subsequent output. The expression following the keyword 
PR# should evaluate to a number between 0 and 7, designating the 
expansion slot to which output is to be sent. 

When Applesoft is started up, it is set to send output to the display 
screen. Executing a PR# statement with a slot number from 1 to 7 
instructs Applesoft to send output instead to the peripheral output de¬ 
vice (such as a printer, terminal, or modem) connected to the desig¬ 
nated slot. A slot number of 0 reestablishes the display screen as the 
current output device. For example, the following program fragment 
writes a string of characters to the device connected to slot 1, then re¬ 
establishes screen output: 

GIO PR# 1 —send output to device in slot 1 

G20 PRINT Z$ —write contents of string vari¬ 

able Z $ to device in slot 1 

G30 PR# 0 —send future output to screen 


Notice that the character # is part of the keyword PR# and cannot 
be omitted. 
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IN# statement: see Section 5.1.1 Restarting the System with P R#: If the slot designated in an IN# or 

PR# statement contains a disk controller card, Applesoft will attempt to 
Be careful ! restart (often called “booting”) the system from the disk contained in 

drive 1 connected to that slot. When you do this on purpose, it's the 
usual way of restarting the system from within Applesoft; when you do It 
by mistake, It can be a catastrophe. 



I CONTROL H RESET | : See Section 1.3.2 


Warning 

If no output device is connected to the slot designated in a PR# state¬ 
ment, the system will hang. To recover, use | control | - |reset| . 

A slot number between 8 and 2 5 5 will cause unpredictable and possi¬ 
bly aberrant behavior. 



If you are using the Ap ple He 80-Column Text Card, always be sure to 
deactivate It by typing | esc 11 control | -Q before using PR# to transfer 
output to another slot. Leaving the Text Card active while using a printer 
or while restarting the system from a disk may produce amusing but 
confusing fireworks on the screen. 

Although the Text Card is installed in the Apple lie’s special auxiliary 
slot, it appears to the computer as if it were in slot 3. So to reactivate the 
Text Card after sending output to another device, type 

PR# 3 

You can also return output to the 40-column screen with the Text Card 
inactive by typing 

PR# 0 

However, don’t use PR# 0 to redirect output directly from the Text 
Card to the 40-column screen without first deactivating the Text Card 
with I ESC 11 CONTROL | -Q. Under Certain circumstances, this may cause 
text intended for the screen to be written outside the area of memory 
reserved for it, possibly destroying your Applesoft program or other 
important information. 


A slot number less than 0 or greater than 255 will stop the program 
with the message 

7ILLEGAL QUANTITY ERROR 
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5.2.2 

The PRINT Statement 


PRINT 

PRINT Qf R1 

PRINT "DISCRIMINANT = "! B-2 - a*A*C 

PRINT LEFT$ (FN$» 1) + + LN$ 

PRINT TAB (M)5 TAB (M + N)! 

"***" ; TAB (M + N + N) ; 

PRINT writes to the current output 
device 

The PRINT statement writes output to the current output device. 
Expressions representing the values to be written are listed after the 

current output device: see Section 

5.2.1 

keyword PRINT, separated by commas or semicolons. 

number formats: see Section 5.2.3 

Any expression may be included in a PR I NT statement. Each 
expression in the list following the keyword P RIN T is evaluated. If 
the value of the expression is a string, the characters of the string are 
written to the current output device; if the value is a number, it is writ¬ 
ten according to the rules discussed in Section 5.2.3, “Number For- 

S PC function: see Section 5.2.4 

mats.” Calls to the special functions S P C and TAB may also be 
included in a P RIN T list; they do not cause anything to be written, 

T AB function: see Section 5.2.4 

but control the positioning of the next item. 

Semicolon suppresses space after an 
item 

When an item in the PR I NT list is followed by a semicolon, the cur¬ 
sor (if output is going to the screen) or print head (if to a printer) is left 
positioned immediately after the last character in the item. The next 
item written will begin iti the next available column, with no interven¬ 
ing spaces. A semicolon at the end of a P RIN T statement causes 
the cursor or print head to be left at the end of that line, and prevents 
a new line from being started. For example, the statement 

PRINT i; 25 35 4! 

will produce the output 

1234 

and will leave the cursor or print head positioned in the column imme¬ 
diately following the digit 4. The statement 

PRINT 1/35 (2 * 4); 51 

will produce the output 


♦333333333851 
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80-Column Text Card: see Apple lie 
Owner's Manual, Apple lie 80-Column 
Text Card Manual 


concatenation: see Section 4.2.2 


If two consecutive items in a P RIN T list are not separated by either a 
comma or a semicolon, a semicolon is understood. 


The Apple lie’s normal display is 40 columns wide. After Applesoft dis¬ 
plays the 40th character on a line, it automatically sends the cursor to 
the beginning of the next line. The next PRINT statement executed will 
start another new line, causing an unintended blank line to appear on 
the screen. This happens even if you have the Apple lie 80-Column Text 
Card installed and running in “active 80” mode; Applesoft doesn’t know 
about the 80-column display and will still break each output line after 40 
characters. 

For example, the statements 

10 PRINT "THIS MESSAGE HAS PRECISELY 40 
CHARACTERS" 

20 PRINT "SO THERE'S A BLANK LINE ON THE 
SCREEN" 

will display the output 

THIS MESSAGE HAS PRECISELY 40 CHARACTERS 

SO THERE'S A BLANK LINE ON THE SCREEN 

To eliminate the blank line, add a semicolon to the end of line 10: 

10 PRINT "THIS MESSAGE HAS PRECISELY 40 
CHARACTERS"5 

Now you’ll get this: 

THIS MESSAGE HAS PRECISELY 40 CHARACTERS 
SO THERE'S A BLANK LINE ON THE SCREEN 

The second line of this message is now a lie. 


A statement such as 
PRINT A$ •¥ B$ 
causes a halt with the message 
7STRING TOO LONG ERROR 

if the combined length of the concatenated strings is greater than 255. 
However, you can print the apparent concatenation regardless of length 
by using a semicolon: 

PRINT A$5 B$ 
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Comma advances to next tab position 

When an item in the PR I NT list is followed by a comma, the cursor 

■ 1 

or print head is advanced to the next available tab position: column 

17 or 33 of the current line or column 1 of the next line. The next item 
written will begin at the tab position. A series of consecutive commas 
will advance the cursor or print head a corresponding number of tab 
positions. A comma at the end of a P RIN T statement causes the 
cursor or print head to be left at the next available tab position, and 
may prevent a new line from being started. For example, the 
statement 

PRINT 1 > 2f 3f iif 

will produce the output 

1 2 3 

a 

and will leave the cursor or print head positioned in column 17 of the 
second line, directly under the digit 2. The statement 

PRINT 1/3 » (2 * 4) j 51 

will produce the output 

.333333333 8 51 

80-Column Text Card: see Apple He 
Owner’s Manual, Apple He 80-Column 
Text Card Manual 

If any character appears in columns 24 to 32, or if you have the Apple He 

80-Column Text Card installed in your computer and running in “active 

80” mode, then column 33 is not available as a tab position; a comma 
after column 17 will cause the next item to start at column 1 of the next 
line. 

text window: see Section 5.2.4, Section 
F.1, and the Apple He Reference Manual 

If the text window is set to fewer than 33 columns wide, commas in a 

PRINT statement do not function properly and may cause text to be 
displayed outside the text window. 

A P R IN T statement that doesn’t end with a comma or semicolon al¬ 
ways starts a new line after writing its last item and leaves the cursor 
or print head positioned in column 1 of the new line. The statement 

PRINT 

P RIN T by itself starts a new line 

simply starts a new line. If the cursor or print head was already at the 
beginning of a line, this statement causes a blank line to be displayed 
or printed. 
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Here’s an example program using some of the features of P RIN T 
discussed above: 


10 

LET A 

= 5.35 

i LET C$ = "FRED" ; LET 


Q1 

= IG 

—set up series of variables 

20 

PRINT 

"STUFF 

AND NONSENSE" 

—display message and start 
new line 

30 

PRINT 


—display a blank line 

40 

PRINT 

"A = "5 

—display message without start¬ 
ing a new iine 

50 

PRINT 

A 

—display 5« 35 on same line as 
message from program line 
40; start new line 

GO 

PRINT 

"GI - " 

; G '1 —display message and value 

1G on same line; start new 
line 

70 

PRINT 

"C$ = " 

* C $ —display message, advance to 
next tab position, and display 
string FRED; start new line 

80 

PRINT 

A * Q1 

—display value of expression 

A * GZ (85 . G) and start 
new line 


When executed, this program will produce the following output: 


STUFF AND NONSENSE 

A = 5*35 
Q1 = IS 

C$ = FRED 

85*B 


? stands for PRINT 


Abbreviation: You can use a question mark (?) as an abbreviation for 
the keyword P RIN T; if you use it, it appears asPRINTina program 
listing. If you type 

100 ? A$ —display string A $ 

LIST —list program 

Applesoft will display 


100 PRINT A$ 


—Applesoft sees ? as PR I NT 
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5.2.3 Number Formats 


Ranges of numeric values 


All arithmetic done on reals 

truncate: to convert a real number to the 
next lower integer 

Rules for number formats 


This section describes the formats in which Applesoft displays or 
prints numeric values. Numbers may not always be formatted in the 
way you might expect; this is particularly true for numbers more than 
nine digits long or for exceptionally small numbers. 

Numeric values in Applesoft must be in the range — 1 * 10" 3 8 to 
1 * 10 '■ 38. Any number whose absolute value is less than approxi¬ 
mately 3 * 10 - 3 3 is converted to zero. True integer values to 
be assigned to integer variables (such as AZ) must be in the range 
-32787 to 4-32787. 

A number typed from the keyboard or a numeric constant used in an 
Applesoft program may have as many as 38 digits. However, only 
nine digits are significant, and the last digit is rounded off. An Apple¬ 
soft statement that you type as 

PRINT 1.23458787854321 

—you type this from the 
keyboard 


will display 


1.23458788 


—you get this on the screen 


on the screen. 

Integers are always converted to real form before being used in arith¬ 
metic calculations, and the results are converted back to integer form 
when assigned to an integer variable. Conversion from real to integer 
form is by truncation to the next lowest integer, not by rounding to the 
nearest integer. 

Applesoft displays and prints numbers according to the following 
rules; 

• If the number is negative, it is preceded by a minus sign (-); if it is 
zero or positive, no sign is used. 

• If the number is an integer with an absolute value from 0 to 
380 883 333, it is formatted as an integer. 
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• If the number is not an integer and its absolute value is between 
. 01 and 993 999 999.2, it is formatted with a decimal 
point in the usual way. 

• In all other cases, the number is formatted in scientific notation 
(see below). 

Table 5-1 shows examples of the formats used for displaying and 
printing numbers. 

Table 5-1 Number Formats - 


Number 


Output Format 


+ 1 
-1 
6523 
-23.460 
45.72* 10-5 
1 * 10-20 

-12.34567896* 10-10 
1000000000 
999999999 


1 

-1 
G523 
-23*4G 
4572000 
IE+ 20 

- 1♦2345G79E+ 11 
IE+ 09 
999999999 


scientific notation: the representation 
of numbers in terms of powers of 10 

Figure 5-1 Format for Scientific Notation 


sign exponent symbol 


SX* XXXXXXXXESDD 



each X is a digit 


sign of exponent 
digits of exponent_ 


The format Applesoft uses for scientific notation is shown in Figure 
5-1. A sign is shown only if the number is negative. There is always 
exactly one nonzero digit before the decimal point and up to eight dig¬ 
its after it, with trailing zeros suppressed. There are never any lead¬ 
ing zeros; the digit before the decimal point is always nonzero. If 
there is only one digit to print after all trailing zeros are suppressed, 
no decimal point is shown. The letter E (for “exponent”) is always 
followed by a sign and a two-digit exponent. The value of a number 
represented in this form is the number before the E times 10 raised to 
the power after the E. For example. 


PRINT 

35 

* 345 " 

14 

PRINT 

-3. 

14153 * 

5B7 

PRINT 

1 / 

999 


PRINT 

-3 

/ 399 



yields 1 ♦ 1 BaSOOBSE + 37 
■' 5 

yields - 1 ♦ Ba 104BG0E + 14 
yields 1*00100 IE-03 
yields -3 ♦ 003003E~03 
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5.2.4 Formatting Text on the Screen 


POKE statement: see Section 7.1.2 

This section deals with Applesoft’s facilities for controlling the way 
text is formatted and presented on the display screen. For further in¬ 
formation on text formatting, see Section 5.2.2, “The PRINT 

Statement.” 

The TEXT and HOME statements are used to clear text and graph¬ 
ics from the screen. 

SPC, TAB, HTAB, UTAB,and POS control the position of the cur¬ 
sor, which determines where characters are displayed on the screen. 

NORMAL, INMERSE, and FLASH control the form in which text 
characters are presented on the screen. 

The S P E E D = command sets the rate at which characters are 
displayed. 

The POKE statement can be used to set the boundaries of the text 
window within which text is displayed on the screen. 

The TEXT Statement 

TEXT 

TEXT switches from graphics to text 
display 

The TEXT statement instructs Appiesoft to begin dispiaying text on 
the screen; it is usually used to switch from graphics to text display. 

text window: see below 

The text window is set to the full screen (24 lines, 40 characters per 

80-Column Text Card: see Apple He 
Owner’s Manual, Apple lie 80-Column 
Text Card Manual 

line: 80 if the 80-Column Text Card is installed and running in “active 

80” mode). The Applesoft prompt character (3) is displayed in the 
bottom-left corner of the screen, followed by the cursor. 

If the display is already in text mode, the T E X T statement is equivalent 
to the statement 0 T A B 24 (see “The M T A B Statement,” below). 

The HOME Statement 

HOME 

HONE clears the text window 

HOME clears the currently defined text window and sends the cur¬ 

text window: see below 

sor to the top-left corner of the window. If the text window is set to 
the full screen, the cursor is sent to the beginning of iine 1. If the 
computer is dispiaying mixed text and graphics (four lines of text at 
the bottom of the screen), HOME ciears the four text iines and 
sends the cursor to the beginning of line 21. 


Output 


119 










Helpful Hint: To move the cursor to the top-left corner of the screen 
without clearing any text, use 

yjAB and HTAB statements: see MTAB 1 : HTAB 1 

below 

The SPC Function 

The SPC (for “space”) function is used in P RIN T statements to 
write a specified number of spaces to the current output device. The 
numeric argument given to the function specifies the number of 
spaces to be written. If this value is a real number, Applesoft trun¬ 
cates it to the next lowest integer. 

The SPC function can be called only from within a P RIN T state- 
TAB function: see below ment. SPC differs from T AB in that it advances the cursor (or print 

head, if the current output device is a printer) a specified number of 
current output device: see Section columns from its current position, rather than to a specific horizontal 

position from the beginning of the current line. If the cursor is spaced 
past the right edge of the screen or text window, it returns to the be¬ 
ginning of the next line and continues spacing. For example, assum¬ 
ing the text window is set to the full screen and the cursor is initially at 
the left edge, the statements 

10 PRINT SPC (5)5 "HELLO" 

—display HELLO starting in 
column 6 

20 PRINT "THESE"? SPC (10)5 "ARE"5 SPC 
(4)5 "INTERESTING"5 SPC (12)5 
"TIMES" —display THESE, 10 

spaces, ARE,4spaces, 
INTERESTING, 12spaces, 
TIMES 


SPC displays spaces on the screen 
PRINT statement: see Section 5.2.2 


will display the following on the screen: 

HELLO 

THESE ARE INTERESTING 

TIMES 

Notice how the output of line 2 0 “wraps around” when it reaches the 
edge of the screen (column 40). 


S P C at end of P RIN T suppresses new If S P C is the last item in a P RIN T statement, Applesoft acts as if the 
line Statement ended with a semicolon. The cursor is left positioned the 

specified number of spaces after the end of the previous item; no new 
line is started. The next item displayed will begin immediately following 
the last space. 
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The argument given to S P C must be in the range 0 to 25 5 or the pro¬ 
gram will halt with the message 

2IL.LEGAL QUANTITY ERROR 

However, several calls to S P C can be strung together in the form 

PRINT SPC(255)5 SPC(255); SPC(255) 

to provide arbitrarily large numbers of spaces. 


Semicolons are optional between S P C items: 

PRINT "LET"; SPC <10) "ALL" SPC (15); 
"REJOICE" 


The TAB Function 


T A 6 advances cursor to a specified 
horizontai position 

PRINT statement; see Section 5.2.2 


The TAB function is used in P RIN T statements to advance the cur¬ 
sor to a specified horizontal position from the beginning of the current 
output line. The numeric argument given to the function specifies the 
position to which the cursor is to be moved. If this value is a real num¬ 
ber, Applesoft truncates it to the next lowest integer. 


SPC function: see above 

current output device: see Section 
5.2.1 


The TAB function can be cailed only from within a P RIN T state¬ 
ment. TAB differs from S P C in that it advances the cursor (or print 
head, if the current output device is a printer) to a specific horizontal 
position from the beginning of the current line, rather than a specified 
number of columns from the current cursor position. If the cursor is 
advanced past the right edge of the screen or text window, it returns 
to the beginning of the next line and continues advancing. For exam¬ 
ple, assuming the text window is set to the full screen and the cursor 
Is Initially at the left edge, the statements 


10 PRINT TAB (15) ; 

20 PRINT TAB (10) ; 
"THERE»"5 TAB 


"THE FLEET'S IN!" 

—display THE FLEET'S IN! 
starting at column 15 
"HELLO"; TAB (30); 

(45) ; "SAILOR! " 

—display H E L L □ at column 10, 
THERE t at column 30, 
SAILOR! at column 5 of 
next line 



will display the following on the screen; 

THE FLEET'S IN! 

HELLO THERE » 

SAILOR! 
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Notice how the output of line 2 0 “wraps around” when it reaches the 
edge of the screen (column 40). 


HT AB statement; see below 


T A B at end of P RIN T suppresses new 
line 


H T A B moves cursor to a specified 
horizontai position 


Unlike the H T A B statement, which moves the cursor to an absolute hor¬ 
izontal position from the left edge of the screen or the text window, TAB 
moves the cursor in a forward direction only. If the specified tab position 
is less than the current cursor position, T AB has no effect; it will never 
move the cursor to the left on the current line (use H T A B for this 
purpose). 


If T A B is the last item in a P RIN T statement, Applesoft acts as If the 
statement ended with a semicolon. The cursor is left at the specified tab 
position; no new line is started. The next item displayed will begin at the 
tab position. 


The argument given to T A B must be in the range 0 to 255 or the pro¬ 
gram will halt with the message 

7ILLEGAL QUANTITY ERROR 

An argument value of 0 moves the cursor to 256 positions from the be¬ 
ginning of the current line. 


Semicolons are optional between TAB items: 

PRINT "DOWN"; TAB (14) "YOU" TAB (27); "GO" 

The HTAB Statement 

HTAB 10 
HTAB N 

HTAB 41 - LEN (S$) 


HTAB (for “horizontal tab”) moves the cursor to a specified horizon¬ 
tal position from the beginning of the current output line. The expres¬ 
sion following the keyword HTAB specifies the position to which the 
cursor is to be moved. If this value is a real number, Applesoft trun¬ 
cates it to the next lowest integer. 
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TAB function: see above Unlike the T A B function, which moves the cursor in a forward direc- 

ut/\b .k tion only, the HTAB statement can move the cursor in either direction 

direction to a specified horizontal position. For example, the program 

5 HOME —clear text from screen 

10 HTAB G : PRINT "IS THE "5 

—display IS THE starting at 
column 6 

15 FOR Z = 1 TO 500: NEXT Z 

—delay loop so user can see the 
order and position of text 
display 

20 HTAB 1 : PRINT "THIS "5 

—display THIS at column 1 
25 FOR Z = 1 TO 500 : NEXT Z 

—another delay loop 

30 HTAB 13 : PRINT "PROPER ORDER" 

—display PROPER ORDER at 
column 13 

will display the following on the screen: 

BB THIS IS THE PROPER ORDER 

If you want to use H T A B to display several text items on the same line, 
you need a semicolon at the end of each PRINT statement, as in the 
program above, to avoid starting a new line. 

text window: see below If there is a text window set, the specified tab position is interpreted 

relative to the left edge of the window. However, HTAB behaves as 
though there were 40 columns in each line of the window, regardless 
of the actual width to which the window has been set; that is, position 
1 is considered to be the leftmost column of the current line, position 
41 the leftmost column of the next line, position 81 the leftmost col¬ 
umn of the line after that, and so on. If the cursor is advanced past the 
right edge of the screen or text window, it returns to the beginning of 
the next line and continues advancing. 

HTAB can carry the cursor outside the boundaries of the text 
window, but only long enough to display one character; the cur¬ 
sor then returns to the left edge of the window. 
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80-Column Text Card: see Apple lie 
Owner’s Manual, Apple lie 80-Column 
Text Card Manual 


POKE statement: see Section 7.1.2 


0 T A B moves cursor to a specified 
vertical position 


80 -Column Text Card Users: HTAB is designed to operate with a 
40-column screen only. If you attempt to advance the cursor beyond 
column 40, it will “wrap around” to the next line, even if you have the 
Apple Me 80-Column Text Card installed and running in “active 80” 
mode. To tab to a position between columns 41 and 80, use 

POKE 36» XX 

where X X the number of the column to which you want to tab. See 
Section F.1 and the 80-Column Text Card Manual for more information. 


The column number specified to H T A B must be in the range 0 to 2 5 5 
or the program will halt with the message 

?ILLEGAL QUANTITY ERROR 

A value of 0 moves the cursor to 256 positions from the beginning of the 
current line. 


Many programmers find H T A B to be more convenient to use than TAB, 
because it is an independent statement and need not be embedded in a 
PRINT statement. This makes it easier to change, if necessary, during 
program development. 


The M T A B Statement 

MTAB 10 
OTAB N 

MTAB 25 - H';:; 


MTAB (for “vertical tab”) moves the cursor vertically to a specified 
line on the screen. The expression following the keyword MTAB 
specifies the line to which the cursor is to be moved. If the value of 
this expression is a real number, Applesoft truncates it to the next 
lowest integer. 

The top line of the screen is line 1; the bottom line is line 24. MTAB 
may move the cursor either up or down on the screen, but never to 
the left or right; it remains at the same horizontal position as before 
the move. For example. 


10 HOME 

—clear text from screen 

20 MTAB B 

—move cursor to line 6 

30 PRINT "LINE B" 

—display imaginative message 
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Text window ignored 


POS yields current horizontai cursor 
position 


Argument required but ignored 


40 

FOR Z 

= 1 

TO 500 

: NEXT Z 

—delay loop so user can see the 
order and position of text 
display 

50 

UTAB 1 

8 


—move cursor to line 18 

GO 

PRINT 

"LINE 18" 

—display another imaginative 
message 

70 

FOR Z 

- 1 

TO 500 

; NEXT Z 
—another delay loop 

80 

UTAB 1 



—move cursor to line 12 

90 

PRINT 

"THE 

MIDDLE 

" —display last message 


M T A B ignores the setting of the text window, if any. The specified line 
number is always taken to refer to the entire screen. 

The line number specified to M T A B must be in the range 1 to 2 4 or the 
program will halt with the message 

7ILLEGAL QUANTITY ERROR 


If M T A B moves the cursor to a line below the bottom of the text window, 
all subsequent text will be displayed on that same line. 


The POS Function 

The POS (for “position”) function yields the current horizontal posi¬ 
tion of the cursor, relative to the left edge of the screen or text window. 
The value yielded is in the range 0 to 39 (0 to 79 if the Apple He 
80-Column Text Card is installed and running in “active 80” mode). A 
value of 0 represents the left edge of the screen or window. 

Strange but True: The argument given to POS is ignored, and has no 
effect on the operation of the function. However, you can’t leave it out— 
you must include an argument expression of some kind to “keep the pa¬ 
rentheses apart.” What you use for an argument expression doesn’t 
matter, but if Applesoft can’t evaluate it as a legal expression, you’ll get 
an error halt. 
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POS, TAB, and HTAB disagree 


IMMERSE displays text in black-on- 
white 


NORMAL statement : see below 


PRINT statement: see Section 5.2.2 


A Difference of Opinion: Notice that P 0 S numbers columns beginning 
with 0, whereas TAB and HTAB number them beginning with 1. Thus, 
assuming the cursor is at the beginning of a line, the statement 

PRINT TAB (10); POS (0) —tab to column 10 and display 

position 


will display the value 9, and 

HTAB 43 : PRINT POS (X) 

—tab to column 43 and display 
position 

will display 2 (since HTAB 43 tabs to the third column of the next dis¬ 
play line). Notice in the second case that the value of variable X makes 
no difference. 

The INVERSE Statement 
INVERSE 


The INVERSE statement causes subsequent text output to be 
displayed in black-on-white instead of the usual white-on-black 
(where “white” means the phosphor color of your display, whatever 
that is). The normal white-on-black display can be restored with the 
NORMAL statement. For example. 


10 INVERSE —set inverse display 

20 PRINT "BLACK-ON-WHITE" 

—display BLACK-ON- 
WHITE in black-on-white 

30 NORMAL —restore normal display 

40 PRINT "WHITE-ON-BLACK" 

—display WHITE-ON- 
BLACK in white-on-black 

INVERSE affects only subsequent output characters sent to the 
screen with PRINT statements. It has no effect on characters al¬ 
ready on the screen or on keyboard input “echoed” to the screen. 

Don’t Overdo It: IN V E R S E is most effective when you use it sparingly. 
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Th 0 FLASH Statement 


FLASH causes text to flash on the 
screen 


NORMAL statement: see below 


PRINT statement: see Section 5.2.2 


ASCII codes: see Section 4.2.1 and 
Appendix C 


80-Column Text Card: see Apple lie 
Owner’s Manual, 80-Column Text 
Card Manual 


FLASH 


The FLASH statement causes subsequent text output to alternate 
approximately twice a second between biack-on-white and the usual 
white-on-black (where “white” means the phosphor color of your dis¬ 
play, whatever that is). The normal white-on-black display can be re¬ 
stored with the NORMAL statement. For example, 


10 

FLASH 


20 

PRINT 

"FLASHY" 

30 

NORMAL 


40 

PRINT 

"DRAB" 


—set flashing display 
—display flashy FLASHY 
—restore normal display 
—display drab DRAB 


FLASH affects only subsequent output characters sent to the 
screen with PRINT statements. It has no effect on characters al¬ 
ready on the screen or on keyboard input “echoed” to the screen. 

FLASH doesn’t work on characters with ASCII codes above 95, the 
most important of which are the lowercase letters; instead of making 
them flash, it turns them into gibberish. FLASH doesn’t work at ali if you 
have the Appie lie 80-Coiumn Text Card installed and running in “active 
80” mode. 


A Little Dab’ll Do Ya: FLASH is most effective when you use it very 
sparingly. Reserve it for only the most important messages or unusual 
uses. Cavalier use of F L A S H has been known to drive users to 
delirium. 
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The NORN A L Statement 


NORMAL displays text in white-on- 
black 

INMERSE and FLASH statements: 
see above 


PRINT statement: see Section 5.2.2 


S P E E D = sets rate of text output 


NORMAL 


The NORMAL statement causes subsequent text output to be dis¬ 
played in the usual white-on-black (where “white” means the phos¬ 
phor color of your display, whatever that is). It is usually used to 
cancel the effects ofthelNUERSEorFLASH statement. For 
example, 


10 

20 


30 

ao 


50 

GO 

70 

80 


I NMERSE —set inverse display 

PRINT "6LACK-0N-WHITE" 


—display BLACK-ON- 
WHITE in black-on-white 

NORMAL —restore normal display 

PRINT "WHITE-ON-BLACK" 

—display WHITE-ON- 
BLACK in white-on-black 

FLASH —set flashing display 

PRINT "FLASHY" —displayflashyFLASHY 

NORMAL —restore normal display 

PRINT "DRAB" —displaydrab DRAB 


NORMAL affects only subsequent output characters sent to the 
screen with PRINT statements. It has no effect on characters al¬ 
ready on the screen. 


The SPEED = Statement 

SPEED= 255 
SPEED= X 
SPEED= Z - G * F 


The S P E E D = statement sets the rate at which output characters 
are sent to the display screen or other output device (such as a 
printer). The slowest rate is 0; the fastest is 2 5 5. The normal speed 
setting (if you don’t do anything to change it) is 255. For example. 


10 

SPEED 

= 0 

—set slowest possible speed 

20 

PRINT 

"THE 

TORTOISE" 




—displayTHE TORTOISE 




slowly 

30 

SPEED 

= 255 

—restore normal speed 

40 

PRINT 

"THE 

HARE" —display THE HARE quickly 
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S P E E D isn’t a variable 


POKE statement: see Section 7.1.2 


PEEK function : see Section 7.1.1 
POKE statement: see Section 7.1.2 


Notice that the equal sign is part of the keyword S P E E D =; it doesn’t 
represent an assignment to a variable named S P E E D. A statement 
such as 

LET SPEED = K 

will cause a syntax error. The only way to find out the current speed 
setting is to keep track of it yourself with a variable, as in the following 
example: 

10 LET X = 250 —set initial value for speed 

20 SPEED = X —set speed to value of X 

30 PRINT "CURRENT SPEED IS X 

—display current speed 

^0 LET X = X - 25 —decrease value of X by 25 

50 IF X >= 0 THEN GOTO 20 

—repeat until X becomes 
negative 

BO SPEED = 255 : END —X is too low; end the program 
The speed setting is not reset to its normal value by R U N, C L E A R or 

I CONTROL | - | RESET | . 


The speed setting specified to S P E E D = must be in the range 0 to 
2 5 5 or the program will halt with the message 

7ILLEGAL QUANTITY ERROR 

The Text Window 

The “window” within which text is displayed and scrolled on the 
screen can be set to less than the full screen through the magic of the 
POKE statement. See Section F.1 for details and the Apple He Refer¬ 
ence Manual for a more technical discussion. 


Miscellaneous Output Facilities 

This section covers Applesoft’s facilities for dealing with the remain¬ 
ing output features of the Apple He: the built-in speaker, annunciator 
outputs, utility strobe, and cassette tape output. Most of these fea¬ 
tures are controlled by means of P E E K and POKE; details can be 
found in Appendix F, “Peeks, Pokes, and Calls.” The annunciators 
and utility strobe are seldom used, and are mentioned here just for 
the sake of completeness. 
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Controlling The Speaker 

The Apple lie has a small, built-in speaker that you can use to add 
sound to your programs. The easiest way to use it is by sending the 
CONTROL l -G sounds the “bell” ASCII “bell” character ( | control | -G, ASCII code 7) to the display 

screen. This causes the computer to emit a short “beep.” 

Historical Note: ASCII code 7 was originally used to ring a small bell on 
teletype machines, to let the teletype operator know that a message was 
coming in. On the Apple Me it sends a 1-kilohertz tone (1000 cycles per 
second) to the computer’s speaker for 1/10 second. 

Here’s a program to ring the computer’s “bell” a number of times 
specified by the user: 

10 PRINT "ENTER A NUMBER FROM 1 TO 9 
(S TO STOP):"; —prompt user for input 

20 GET A$ —accept single character from 

keyboard 

30 IF A$ = "S" THEN END 

—stop if user typed S 

40 IF MAL (A$) < 1 THEN 20 

—if character typed is out of 
range then try again 

50 FOR K = 1 TO MAL (A$) 

—loop requested number of 
times 

BO PRINT CHR$ (7) —sound“bell” 

70 NEXT X —loop back to 50 

SO PRINT —leave a blank line 

00 GOTO 10 —start again 

The only other way to produce sound from the speaker is with a 
PEEK or POKE to address - 1B3 36. This causes the speaker to 
emit a single “click.” By combining such clicks in the appropriate pat¬ 
terns and frequencies, you can produce musical tones and a variety 
of other sounds. Experiment for yourself! 

For technical information on the built-in speaker, see the Apple He 
Reference Manual. 
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annunciators: see Apple He Reference 
Manual 


utility strobe: see Apple He Reference 
Manual 


SAME command: see Section 1.2.5 and 
Appendix M 

STORE statement: see Appendix M 


Annunciator Output 

The Apple Me has four annt/nc/afor outputs, which are pins of the 
hand control connector on which electrical impulses can be transmit¬ 
ted. The signals on these pins are most commonly used to control 
devices such as lamps and relays connected to the computer 
through the hand control connector. The annunciator outputs can be 
turned on and off with P E E K or P □ K E to the appropriate addresses; 
see Section F.4 for details and the Apple He Reference Manual for 
further technical information. 

The Utility Strobe 

The Apple I le’s utility strobe is a pin of the hand control connector that 
can be triggered to send an electrical impulse lasting one-half micro¬ 
second. Like the annunciators, it can be used to control a variety of 
devices connected to the computer through the hand control connec¬ 
tor. The utility strobe can be triggered with a P E E K or P 0 K E to ad¬ 
dress - 1B 3 2 0: see Section F.4 for details and the Apple He 
Reference /Wanua/for further technical information. 

Cassette Output 

Two Applesoft statements, SAME and STORE, can be used to write 
information to a cassette tape recorder. SAME writes the Applesoft 
program currently in memory to tape; STORE writes the contents of 
an integer or real array. For details, see Appendix M, “If You Have a 
Cassette Recorder.” 
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low-resolution graphics: see Section 
6.1 

high-resolution graphics: see Section 
6.2 

shape tables: see Section 6.3 


GR statement: see Section 6.1.1 

COLOR = statement: see Section 6.1.2 

PLOT statement: see Section 6.1.3 
HLIN statement: see Section 6.1.4 
ML IN statement: see Section 6.1.5 
S CR N function: see Section 6.1.6 


Chapters 


Graphics 


This chapter describes Applesoft’s facilities for creating, changing, 
displaying, and storing both low- and high-resolution graphic 
designs. 

Section 6.1, “Low-Resolution Graphics,” deals with 16-color graphics 
on a 40-by-48 grid. 

Section 6.2, “High-Resolution Graphics,” deals with 6-color graphics 
ona280-by-192grid. 

Section 6.3, “Shape Tables,” discusses the use shape tables for 
animation sequences. 

Low-Resolution Graphics 

The low-resolution graphics screen consists of 1920 blocks (40 col¬ 
umns by 48 rows) in 16 colors. This section describes the facilities 
available in Applesoft for using low-resolution graphics: 

• The G R statement instructs Applesoft to begin displaying low- 
resolution graphics. 

• The C 0 L □ R = statement controls the colors displayed on the 
screen. 

• The PLOT statement plots individual blocks on the screen. 

• The H LIN statement draws horizontal lines. 

• The M LIN statement draws vertical lines. 

• The S C R N function determines what color is currently displayed 
at any position of the screen. 
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6.1.1 The GR Statement 



GR 

GR displays low-resolution graphics 

The G R (for “graphics”) statement instructs the computer to display 
low-resolution graphics. If the screen has been displaying text, it is 
changed from 40 (or 80) coiumns by 24 lines of text to 40 columns by 
40 rows of graphics, with space for four lines of text at the bottom. 

TEXT statement: see Section 5.2.4 

(Full text dispiay can be restored with the TEXT statement.) GR 
clears the screen to black, moves the text cursor to the beginning of 

text window: see Section 5.2.4 

the bottom line (line 24), clears any text window that may have been 
set, and sets the low-resolution display color to 0 (black). 

After executing a G R statement, you can convert the display to full¬ 
screen graphics (a 40-by-48 grid with no space for text) with the 
statement 

POKE statement: see Section 7.1.2 

POKE -1B302»0 

This statement will change the bottom four lines of text to eight rows 
of colored blocks. To clear these rows to black, add 

CALL -1008 

Notice that the P 0 K E statement above must be executed after G R. If 
you execute the P 0 K E first, G R will reset the screen to mixed graphics 
and text. 

high-resolution page 2: see Section 
6.2.2 

If you execute a G R statement while displaying high-resolution page 2, 

G R clears its usual screenful of memory but leaves you looking at page 

2 of low-resolution graphics and text. To avoid this problem, always use 
the T E K T statement before switching from high-resolution page 2 to 
low resolution. 

For more information... 

See Section F.3 for more information on the use of the various text and 
graphics memory pages. See the Apple He Reference Manual for fur¬ 
ther technical information on the Apple lie’s graphics display 
capabilities. 
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6.1.2 The COLOR = Statement 

COLOR= 12 
COLOR= C(J) 

COLOR= (X - 4) / IG 


c 0 L 0 R = sets low-resolution display The C 0 L 0 R = Statement sets the display color for plotting low- 

resolution graphics. There are 16 colors available, represented by 
numbers from 0 to 15 as shown in Table 6-1. When you enter 
low-resolution graphics, the G R statement sets the display color to 
black (0). 


Table 6-1 Color Codes for Low-Resolu- 


tion Graphics 

Code 

Color 

Code 

Color 


0 

black 

8 

brown 


1 

magenta 

9 

orange 


2 

dark blue 

10 

grey-2 


3 

violet 

1 1 

pink 


4 

dark green 

12 

green 


5 

grey-1 

13 

yellow 


e 

medium blue 

14 

aqua 


7 

light blue 

15 

white 


If you’re using a monochrome display (black-and-white, or some other 
single phosphor color), the different colors will appear on your screen as 
various patterns of shading. 

The following short program displays each of the 16 available colors 
in a horizontal bar across the screen: 


10 

GR 


—display low-resolution 




graphics 

20 

FOR X = 0 

TO 

15 —execute loop for each color 

30 

COLOR= X 


—set next color 

H LI N statement: see Section 6. 1.4 4 0 

HLIN 0» 39 

AT 

V 

A * 




—draw a bar of this color across 




the screen, leaving a blank 
row above it 

50 

NEXT X 


—go back for next color 
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COLOR isn’t a variable 


PLOT draws a single block 

low-resolution display color: see 

Section 6.1.2 


Notice that the equal sign is part of the keyword C 0 L 0 R =; it doesn’t 
represent an assignment to a variable named C 0 L 0 R. A statement 
such as 

LET COLOR= X 

will cause a syntax error. The only way to find out the current display 
color is to keep track of it yourself with a separate variable, as In the 
example above. 


You can specify a color code higher than 15, but the series of color val¬ 
ues simply repeats. That is, 1S is equivalent to 0, 18 is equivalent to 2, 
3 5 is equivalent to 3, and so on. However, a color value less than 0 or 
greater than 255 will stop the program with the message 

7ILLEGAL QUANTITY ERROR 


6.1.3 The PLOT Statement 

PLOT 20* 12 
PLOT K - S » Y + 2 
PLOT THETA * 40 / (2#PI)» 24 - 
(SIN(THETA) * 23) 


The PLOT statement places a block of the current low-resolution 
display color at a specified position on the screen. The first expres¬ 
sion following the keyword PLOT specifies the column in which the 
block is to be plotted (numbered 0 to 3 3, from left to right); the sec¬ 
ond expression, separated from the first by a comma, designates the 
row (numbered 0 to 3 0 for mixed text and graphics, 0 to 4 7 for full¬ 
screen graphics, from top to bottom). For example, the following pro¬ 
gram plots a block of pink in column 20, row 2 of the screen: 


10 

GR 

—display low-resolution 



graphics 

20 

C0L0R= 11 

—set display color to pink 

30 

PLOT 20 > 2 

—plot a block of pink in column 



20, row 2 


Figure 6-1 shows the system of coordinates used to designate posi¬ 
tions on the low-resolution graphics screen. Position 0 * 0 is the top- 
left corner and position 39 »0 the top-right. When displaying mixed 
graphics and text, the bottom-left corner is position 0 >33 and the 
bottom-right is 3 9 ♦ 3 9; in full-screen graphics, the bottom-left cor¬ 
ner is 0 » 4 7 and the bottom-right is 3 9 > 47 . 
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Figure 6-1 Screen Coordinates for Low- 
Resolution Graphics 




_ wm\ 


Ot 0 


0 . 39 
(orO^ 47) 


39 * 0 


39 # 39 
(or 39 # 47) 


If Applesoft Is displaying mixed graphics and text and the plotting coordi¬ 
nates designate a row from 4 0 to 4 7, a text character will be displayed 
at the specified coordinates instead of a block of color. The particular 
character displayed depends on the current low-resolution display color.. 
Here’s a program to demonstrate this effect: 


10 GR 

20 FOR Y = 0 TO 47 
30 FOR K = 0 TO 39 
40 COLOR = K 


50 PLOT Kf Y 
60 NEXT K 
70 NEXT Y 

Try changing line 10 to 

10 TEXT 


—display mixed low-resolution 
graphics 

—loop over all screen rows 
—loop over all screen columns 
—use color corresponding to col¬ 
umn number (colors 0 to 15 will 
repeat after column 15) 

—plot a block at column X, row Y 
—loop to next column 
—loop to next row 


to see the effect on the full screen. 


A column coordinate outside the range 0 to 3 9 or a row coordinate out¬ 
side the range 0 to 4 7 will cause the program to halt with the message 

7ILLEGAL QUANTITY ERROR 


6.1.4 The HLIN Statement 

HLIN 5» 20 AT 35 

HLIN Y AT Z 

HLIN 0 - 3» J * SB AT MX 


HLIN draws a horizontal line The HLIN (for “horizontal line”) Statement draws a horizontal line on 

the screen in the current low-resolution display color. The two expres- 
s^'tion 6*1 2 °" sions following the keyword HLIN, separated by a comma, desig¬ 

nate the columns in which the line is to begin and end; the expression 
following the keyword A T specifies the row in which the line is to be 
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M L IN draws a vertical line 

low-resolution display color: see 

Section 6.1.2 


drawn. The first end point may be less than, equal to, or greater than 
the second. For example, 

10 G R —display low-resolution 

graphics 

20 C0L0R= 4 —set color to dark green 

30 HLIN 10 f 30 AT 20 —draw a horizontal green line in 

row 20 from column 10 to col¬ 
umn 30 

If you use HLIN while displaying text instead of graphics, or with a row 
coordinate from 4 0 to 4 7 while displaying mixed graphics and text, 
Applesoft will display a row of characters instead of a bar of color. For 
example, if line 10 above were changed to 

10 TEXT —display text instead of graphics 

the result would be a row of dollar signs instead of a bar of dark green. In 
most cases, when you see patterns like these on your screen it means 
you forgot to include a GR statement. 


A column coordinate outside the range 0 to 30 or a row coordinate out¬ 
side the range 0 to 4 7 will cause the program to halt with the message 

7ILLEGAL QUANTITY ERROR 


The HLIN statement has no visible effect If you use it while displaying 
high-resolution graphics. 


6.1.5 The ^JLl H Statement 

ML IN 5» 20 AT 35 

MLIN X» Y AT Z 

ML IN 0 - 3f J * SB AT 


The M LIN (for “vertical line”) statement draws a vertical line on the 
screen in the current low-resolution display color. The two expres¬ 
sions following the keyword ML IN, separated by a comma, desig¬ 
nate the rows in which the line is to begin and end; the expression 
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6.1.6 

S C R N reads the color at a designated 
screen position 


color codes: see Table 6-1, Section 
6.1.2 


following the keyword A T specifies the column in which the line is to 
be drawn. The first end point may be less than, equal to, or greater 
than the second. For example, 

10 G R —display low-resolution 

graphics 

20 C0L0R= 4 —set color to dark green 

30 ML IN 10 » 30 AT 20 —draw a vertical green line in 

column 20 from row 10 to row 
30 

If you use ML IN while displaying text instead of graphics, or if part of 
the line being drawn goes beyond row 39 while displaying mixed graph¬ 
ics and text, Applesoft will display text characters instead of blocks of 
color. For example, if line 10 above were changed to 

10 TEXT —display text instead of graphics 

the result would be a row of flashing D’s and a dollar sign instead of a bar 
of dark green. 


A column coordinate outside the range 0 to 3 3 or a row coordinate out¬ 
side the range 0 to 4 7 will cause the program to halt with the message 

7ILLEGAL QUANTITY ERROR 


The M LIN statement has no visible effect if you use it while displaying 
high-resolution graphics. 


The SCRN Function 

The SCRN (for “screen”) function reads the color currently displayed 
at a designated position on the low-resolution graphics screen. This 
function takes two arguments, the first specifying the column and the 
second the row of the desired position. It yields a number from 0 to 
15 representing the color displayed at that position. For example, the 
expression 

SCRN (5» 9) 

yields the code for the color displayed at column 5, row 9. 

The SCRN function is not intended for use with high-resolution 
graphics. 
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For Experts Only—Strange Extensions: Although the ordinary limits 
for coordinates on the low-resolution graphics screen are 3 9 and 4 7, 

S CRN will actually accept values up to 47 for both arguments. But if the 
column parameter is greater than the usual limit of 3 9, odd things hap¬ 
pen. The code yielded by S C R N gives the color for the block whose col¬ 
umn is the designated column minus 40, and whose row is the 
designated row plus 16. 

If the row-plus-16 number is in the range 4 0 through 4 7, and if mixed 
graphics and text are being displayed, then the code yielded is not a 
color code, but is related to the text character at that position in the text 
area below the graphics (see “For Experts Only—Reading the Text 
Screen,” below). 

If the row-plus-16 number is in the range 48 to S3, SCRN yields a re¬ 
sult whose meaning is beyond the ken of mere mortals. 

For Experts Only—Reading the Text Screen: When text is being dis¬ 
played, SCRN yields numbers in the range 0 to 15 whose value is 
either the high-order four bits (if the row number is odd) or the low-order 
four bits (if the row number is even) of the character in column C + 1 
and row (R + 1) / 2, where C and R are the column and row 
numbers given as arguments to 9 C R N. Thus the following expression 
will yield the character at position K * Y: 

CHR$ ( SCRN (K - 1 # 2 * (Y - 1 ) + 1) * IS 
+ SCRN (K - 1f 2 * <Y - 1)) ) 

6.2 

High-Resolution Graphics 

There are two separate regions in the Apple lie’s memory, desig¬ 
nated page 1 and page 2, that can be used for displaying high-resolu- 
tion graphics. Each consists of 53,760 points (280 columns by 192 
rows), which can be displayed on the screen in 6 colors. This section 
describes the facilities available in Applesoft for using high-resolution 
graphics: 

HGR statement: see Section 6.2.1 

• The HGR statement instructs Applesoft to begin displaying page 

1 of high-resolution graphics. 

H G R 2 statement: see Section 6.2.2 

• The H G R 2 statement instructs Applesoft to begin displaying 

page 2 of high-resolution graphics. 

H C 0 L □ R = statement: see Section 

6.2.3 

• The H C 0 L 0 R = statement controls the colors displayed on the 

high-resolution screen. 

H PLOT statement: see Section 6.2.4 

• The H P L 0 T statement plots individual points and lines on the 

high-resolution screen. 

protecting programs and graphics: 

see Section 6.2.5 

Section 6.2.5 tells how to protect your programs and high-resolution 
graphics from overwriting each other in the computer's memory. 
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6.2.1 The HGR Statement 

HGR 


The HGR (for “high-resolution graphics”) statement instructs Apple¬ 
soft to display page 1 of high-resolution graphics. If the screen has 
been displaying text, it is changed from 40 (or 80) columns by 24 lines 
of text to 280 columns by 160 rows of high-resolution graphics, with 
space for four lines of text at the bottom. The graphics area of the 
screen is cleared to black; the high-resolution display color is not af¬ 
fected. HGR doesn’t affect the contents of the text screen, the setting 
of the text window, or the location of the text cursor; the cursor will not 
be visible unless it is in one of the bottom four lines of the screen. 

After executing an HGR statement, you can convert the display to full¬ 
screen graphics (a280-by-192 grid with no space for text) with the 
statement 

POKE statement: see Section 7.1.2 POKE -1G302» 0 

This statement will change the bottom four lines of text to high-reso- 
lution graphics. To return to mixed graphics and text, use 

POKE -1B301» 0 


HGR displays high-resolution 
graphics page 1 


high-resolution display color: see 

Section 6.2.3 


Notice that the first P 0 K E statement above must be executed after 
H G R. If you execute the P 0 K E first, H G R wiil reset the screen to mixed 
graphics and text. 

TEXT statement: see Section 5.2.4 The TEXT Statement will return to text display with the text window 

set to the full screen and the cursor at the bottom of the screen. To 
turn off high-resolution graphics and return to text display with the 
text window and cursor intact, use the statement 

POKE -1B303» 0 

protecting programs and graphics: If you intend to use HGR with an Applesoft program longer than about 

see Section 6.2.5 6000 (decimal) bytes, see Section 6.2.5 on how to protect your program 

and graphics from overwriting each other. 


Warning 

If you use the reserved word H G R as the first three characters of a vari¬ 
able name, the HGR statement may be executed before a syntax error is 
detected. For example, executing the statement 


HGRIP = 4 


will unexpectedly turn on high-resolution graphics and may destroy part 
of your program. 
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For more information... 

See Section F.3 for more information on the use of the various text and 
graphics memory pages, and Section H I for the memory locations oc¬ 
cupied by the high-resolution graphics pages. See the Apple He Refer- 
ence Manual for further technical information on the Apple lie’s graphics 
display capabilities. 

6.2.2 

The HGR2 Statement 

HGR2 

HGR2 displays high-resolution 
graphics page 2 

The HGR2 (for “high-resolution graphics, page 2”) statement in¬ 
structs Applesoft to display page 2 of high-resolution graphics. If the 
screen has been displaying text, it is changed from 40 (or 80) col- 

high-resolution display color: see 

Section 6.2.3 

umns by 24 lines of text to 280 columns by 192 rows of high-resolu¬ 
tion graphics. The screen is cleared to black; the high-resolution 
display color is not affected. H G R 2 doesn’t affect the contents of the 

text window: see Section 5.2.4 

text screen, the setting of the text window, or the iocation of the text 
cursor. 

TEXT statement: see Section 5.2.4 

The TEXT statement will return to text display with the text window 
set to the fuli screen and the cursor at the bottom of the screen. To 
turn off high-resolution graphics and return to text display with the 
text window and cursor intact, use the statements 

POKE statement: see Section 7.1.2 

POKE - 1B 3 0 0 » 0 —switch from page 2 to page 1 

POKE - 1B 3 0 3 t 0 —switch from graphics to text 

After executing an H G R 2 statement, you can convert the display to 
mixed graphics and text (a 280-by-160 grid with four lines of text at the 
bottom) with the statement 

POKE -16301» 0 

However, when you use this statement while displaying high-resolution 
page 2, the four lines of text will be taken from text page 2 instead of the 
usual page 1. Since Applesoft uses the same memory locations allo¬ 
cated to text page 2 for program storage, you’ll end up displaying gar¬ 
bage in the bottom four lines of your screen. For this reason, most 
programmers avoid mixing graphics and text when using high-resolution 
page 2. 
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protecting your program : see Section If you intend to use H G R 2 with an Applesoft program longer than about 
6.2.5 1 4000 (decimal) bytes, see Section 6.2.5 on how to protect your pro¬ 

gram and graphics from overwriting each other. 


Warning 

If you use the reserved word H G R 2 as the first four characters of a vari¬ 
able name, the HGR2 statement may be executed before a syntax error 
is detected. For example, executing the statement 

HGR2PIECES = 4 

will unexpectedly turn on high-resolution graphics and may destroy part 
of your program. 


For more information... See Section F.3 for more information on the use of the various text and 

graphics memory pages, and Section H.1 for the memory locations oc¬ 
cupied by the high-resolution graphics pages. See the Apple lie Refer¬ 
ence Manual for further technical information on the Apple lie’s graphics 
display capabilities. 


6.2.3 7/ie HCOLOR = Sfafe/nenf 

HC0L0R= G 
HC0L0R= C(J) 

HC0L0R= (K - 4) / 8 


HC0L0R= sets high-resolution dis¬ 
play color 


Table 6-2 Color Codes for High-Resolu¬ 
tion Graphics 


Code 

Color 

0 

black-1 

1 

green 

2 

violet 

3 

white-1 

4 

black-2 

5 

orange 

6 

blue 

7 

whlte-2 


The H C □ L 0 R = (for “high-resolution color”) statement sets the dis¬ 
play color for plotting high-resolution graphics. There are 6 colors 
available, represented by numbers from 0 to 7, as shown in Table 6-2. 

If you’re using a monochrome display (black-and-white, or some other 
single phosphor color), the different colors will appear on your screen as 
various patterns of shading. 

The high-resolution display color is not affected byHGR,HGR2,or 
RUN. Until your program executes anHC0L0R = statement, the 
display color for high-resolution graphics is indeterminate. 

Notice that the equal sign is part of the keyword HC0L0R = ;it doesn’t 
represent an assignment to a variable named H C 0 L 0 R. A statement 
such as 

LET HC0L0R= K 

will cause a syntax error.The only way to find out the current display 
color is to keep track of It yourself with a separate variable. 
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Curious Behavior: As you wander deeper Into the recesses of the Ap¬ 
ple lie’s graphics system, you’ll begin to notice that the colors in high- 
resolution graphics don’t always act as you might expect. For example, 
carefully drawn vertical lines may refuse to be visible, a white line cross¬ 
ing a field of green may leave jagged blocks of orange in its wake, or a 
point plotted with HCOLOR= 3 (white-1) may look blue if its column 
coordinate is even, green if the column coordinate is odd, and white only 
if a point is plotted in the next column as well. These strange phenom¬ 
ena are a result of the way the Apple lie’s high-resolution graphics fea¬ 
tures interact with the color circuitry in your television set. See the Apple 
lie Reference Manual for further explanation. 


If you specify a color code higher than 7, your program will halt with the 
message 

?ILLEGAL QUANTITY ERROR 


6.2.4 The HPLOT Statement 

HPLOT 140» 80 

HPLOT X - 1B» Y + 12 TO X + IBt Y - 
12 

HPLOT 70j40 to 210»40 TO 210»120 TO 
70^120 TO 70»40 

HPLOT TO THETA * 280 / (2*PI)> 9B - 
(SIN(THETA) * 95) 


HPLOT plots high-resolution points 
and lines 

high-resolution display color: see 

Section 6.2.3 


10 

HGR 

—display high-resolution 



graphics 

20 

HC0L0R= 3 

—set display color to white-1 

30 

HPLOT 100» 50 

—plot a point at column 100, row 


50 

Figure 6-2 shows the system of coordinates used to designate posi¬ 
tions on the high-resolution graphics screen. Position 0 j 0 is the top- 
left corner and position 279 *0 the top-right. When displaying mixed 
graphics and text, the bottom-left corner is position 0 > 159 and the 
bottom-right is 279 >159; in full-screen graphics, the bottom-left 


The HPLOT (for “high-resolution plot”) statement plots points and 
lines on the high-resolution graphics screen in the current high-reso¬ 
lution display color. The first expression in each pair specifies a col¬ 
umn (numbered 0 to 279, from left to right); the second expression, 
separated from the first by a comma, designates a row (numbered 0 
to 15 9 for mixed text and graphics, 0 to 191 for full-screen graph¬ 
ics, from top to bottom). For example, the following program plots a 
white point at column 100, row 50 of the screen: 
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corner is 0 >131 and the bottom-right is 2 7 9 >191. 


Figure 6-2 Screen Coordinates for High- 
Resolution Graphics 


279 . 0 


(or 


?79 
J79 ; 


159 

191) 


0 t 0 


0 » 
(or 0 » 


159 

191) 


To draw a line with H P L 0 T, specify the starting and ending points, 
separated by the keyword TO. The next example draws a white line 
across the screen: 

10 HGR —display high-resolution 

graphics 

20 HC0L0R= 3 —setdisplay color to white-1 

30 HPLOT 0» 50 TO 279» 50 

—draw a line across row 50 

You can draw a series of connected lines in the same HPLOT state¬ 
ment by using a series of T 0 clauses. Each line will begin where the 
last one ended. The following program, for example, draws a rectan¬ 
gle, as illustrated in Figure 6-3: 

10 HGR —display high-resolution 

graphics 

20 HC0L0R= 3 —setdisplay color to white-1 

30 HPLOT 70>40 TO 210>40 TO 210>120 
TO 70>120 TO 70>40 

—draw a rectangle 


Figure 6-3 Drawing a Rectangle with 
HPLOT 



You can extend the series of lines almost Indefinitely within the same 
HPLOT statement, subject only to the limit of 239 characters in a 
program line. 
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HC 0L0R = statement: see Section 
6.2.3 


▲ 


6.2.5 

Apple He memory allocation: see 

Section H.1 


You can also continue from wherever the last H P L 0 T statement 
ended, by writing the keyword T 0 immediately after the word 
H P L 0 T. For example, adding the line 

40 HPLOT TO 210 > 120 —continue drawing from last 

point 

to the previous program will cause it to draw in the diagonal of the 
rectangle, represented by the dashed line in Figure 6-3. Applesoft 
assumes that the starting point (which ordinarily would have ap¬ 
peared between the words HPLOT and T 0) is the last point plotted. 

The color of the new line drawn by H P L 0 T T 0 is the same as that of 
the last point plotted. Even if you insert a new H C 0 L 0 R = statement 
between lines 3 0 and 4 0, the line drawn by the H P L 0 T T 0 In pro¬ 
gram line 4 0 will appear in the same color as those drawn in line 30. 

To change the color of the line, use a whole new HPLOT: 

35 HC0L0R= S —change color to blue 

40 HPLOT 70* 40 TO 210* 120 

— continue drawing from last 
point 


If the screen is displaying mixed text and graphics, an attempt to plot a 
point whose row coordinate is in the range 1 BO to 191 will have no vis¬ 
ible effect. However, if you draw a line either beginning or ending In rows 
160 to 191, Applesoft will display as much of the line as it can. If you later 
switch to full-screen graphics with POKE - 16 3 02 * 0 the hidden por¬ 
tion of the line will appear. 


Warning 

Be sure to precede H PL0T by either HGRorHGR2or you will write 
over lots of memory, including your program and variables. 


If the column coordinate given to H P L 0 T is outside the range 0 to 
279, or the row coordinate outside the range 0 to 191, the program 
will halt with the message 

7ILLEGAL QUANTITY ERROR 


Protecting High-Resolution Graphics 

The two high-resolution graphics pages lie pretty much in the center 
of things: page 1 resides at memory addresses 8192tolG3S3 
(hexadecimal $ 2 0 0 0 to $ 3 F F F) and page 2 at addresses 1B 3 8 4 
to 2 4 5 7 5 (hexadecimal $ 4 0 0 0 to $ 5 F F F). Because Applesoft 
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HGR statement: see Section 6.2.1 


HI MEM : statement: see Section 7.2.1 


HGR2 statement: see Section 6.2.2 


POKE statement: see Section 7.1.2 


program storage begins at location 2048 (hexadecimal $800), it’s 
easy for your program and graphics to get in each other’s way. For 
example, if you’re using the H G R statement to display page 1 of high- 
resolutlon graphics, you have only 6144 bytes of program and vari¬ 
able space (8192 minus 2048) before your program overwrites 
the graphics area. This section tells how to prevent them from collid¬ 
ing, causing untold mayhem and destruction. 

One way to protect your program and graphics from each other is to 
use the HIM E M: statement to set the upper limit of program memory 
at 813 2. This is a reasonable method to use for short programs; but 
Applesoft tends to use a lot of memory, and longer programs would 
soon run out of space. 

Another method that allows the program a bit more breathing room is 
to use the second page of graphics instead of the first (H G R 2 instead 
of H G R). This has the benefit of starting the graphics at a higher 
memory location, so you can setHIHEM:tolB384 instead of 
8192, allowing 14336 bytes (1G384 minus 20 4 8) for your pro¬ 
gram and variable space. The disadvantage of this method is that you 
lose the four lines of text at the bottom of the screen, which are avail¬ 
able with H G R but not with H G R 2. 

A third method, probably the best for long programs with lots of vari¬ 
ables, is to use the wizardry of the P 0 K E statement to change the 
start, instead of the end, of Applesoft’s program storage space. The 
following statements will start program and variable storage above 
graphics page 1, beginning at address 18384 (hexadecimal 
$4000): 

POKE 103j 1 
POKE 104* 64 
POKE 1B384* 0 

These statements will start program and variable storage above 
high-resolution page 2, beginning at address 245 7G (hexadecimal 
$B000): 

POKE 103* 1 
POKE 104* 96 
POKE 2457B* 0 
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No matter where you start program space in memory, your next com¬ 
mand should be 


NEW command : see Section 1.2.1 

NEW 

RUN command: see Section 1.2.4 

to clear out any old variables and system control information so you 
can start afresh program beginning at the new location. (If your com¬ 
puter is equipped with one or more disk drives, you can accomplish 
the same thing by ioading a new program from a disk with the R U N 
command.) 

6.3 

Shape Tables 

Applesoft has a number of special facilities that allow you to manipu¬ 
late shape tables defining shapes on the high-resolution graphics 
screen. Because shape tables have the advantages of both flexible 
design and very fast execution, they are ideal for applications such as 
on-screen animation. This section contains detailed information on 
creating and manipulating shape tables. 

For Hackers Only: Since the advent of the Apple ii series of computers, 
a number of excellent graphics software packages have appeared on 
the market. Available at most computer stores, these packages take the 
hard-core technical work (binary arithmetic and machine-language ma¬ 
nipulation) out of designing and using shape tables. The information in 
this section is intended for those programmers who enjoy ‘‘twiddling the 
bits” themselves. 

To use this section effectively, you’ll need to know about bits and bytes 
and the rudiments of hexadecimal arithmetic. This information is avail¬ 
able in any basic text on computer science; see the bibliography in the 

Apple He Owner’s Manual that came with your computer. All computer 
memory addresses in this section are in hexadecimal; all other num¬ 
bers, unless otherwise noted, are in decimal. 

6.3.1 

Creating a Shape Table 

shape table: a collection of one or more 
shape definitions, together with their 
indices 

An Applesoft shape definition consists of a sequence o\ plotting vec¬ 
tors that are stored in a series of consecutive bytes in the computer’s 
memory. One or more such shape definitions, with their indices (see 
“The Shape Table Index,” below), make up a shape table. 

Plotting Vectors 

plotting vector: a code representing a 
single step In drawing a shape on the 
screen 

Each byte in a shape definition has three sections. Each section may 
contain a plotting vector, specifying whether to plot a point at the cur¬ 
rent screen position and in what direction to move (up, down, left, or 
right) before processing the next vector. Thus each byte can repre¬ 
sent up to three plotting vectors. 
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Figure 6-4 Plotting Vectors in a Byte 


section: 
bit number: 


C B A 

I 7 G 5 4 3 2 1 0| 


Figure 6-4 shows how the three sections are arranged within each of 
the bytes that make up a shape definition. In each plotting vector, bit 
P specifies whether to plot a point before moving, and the pair of bits 
designated DD specify the direction in which to move before pro¬ 
cessing the next vector. 


specifies: DDPDDPD 0 


ifDD 


00 move up 
01 move right 

10 move down 

11 move left 


Notice that the last section in each byte (the two high-order bits, la¬ 
beled C in the figure) does not include a P bit. The value of P in such 
a section is always assumed to be 0 (don’t plot); thus section C can 
only specify a move without plotting. 

How Plotting Vectors Are Interpreted 


if P =0 don’t piot The DRAW and X D R A W statements read through each byte in the 

= 1 plot a point shape definition, from the first byte in the definition to the last. Within 

- each byte, the sections are processed from right to left: section A, 

then B, then C. When a byte is encountered that contains all zeros, 

DRAW and XDR AW statements; see the shape definition is complete. 

Section 6.3.2 


At any section in the byte, if all the remaining sections contain only 
zeros, then those sections are ignored. Thus a byte can’t end with a 
move in section C of 00 (move up without plotting), because that 
Figure 6-5 Plotting a Shape section, containing only zeros, will be ignored. Similarly, if section C 

_ is 0 0 (ignored), then section B cannot be a move of 0 0 0(move up 

without plotting), since that will also be ignored. And a vector of 0 0 0 
a. in section A will end your shape definition unless there is a one bit 

• • • somewhere in section B or C. 


• • 

• • 


• • 


b. 



Coding a Shape Table 

Suppose you want to draw a shape like that shown in Figure 6-5a. To 
convert the shape into an Applesoft shape definition, follow these 
steps: 

1. Draw the shape on graph paper, one dot per square. 

2 . Decide where to start drawing the shape—let’s start this one at 
the center—and draw a path through each point in the shape, us¬ 
ing only 90-degree angles on the turns, as in Figure 6-5b. 

3. Redraw the shape as a series of plotting vectors, each vector 
moving one place up, down, left, or right, and distinguish those 
vectors that plot a point before moving. This step is illustrated in 
Figure 6-5c: vectors that plot before moving are marked in the 
figure with a dot at the beginning of the direction arrow. 
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Figure 6-5 continued 


4. “Unwrap” the vectors and write them out in sequential order, as 
in Figure 6-5d. 



Now you’re ready to code the plotting vectors as a shape definition 
table. Figure 6-6 gives the binary codes corresponding to each pos¬ 
sible vector. For each vector in the shape, determine the proper bit 
code and place it in the next available section in the table, as shown 
in Figure 6-7. If the code won’t fit (for instance, the vector in section C 
can’t plot a point) or is a 0 0 (or 0 0 0) at the end of a byte, then just fill 
that section with zeros. 


Figure 6-6 Codes for Plotting Vectors 


vector code 



move 

only 


plot 

and move 


Figure 6-7 Shape Definition Table 


section 

byte 

1 

2 

3 

a 

5 

G 

7 

8 
0 



cannot plot 


denotes end 
of shape 
definition 


or move up 
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Table 6-3 Hexadecimal Byte Codes 


Binary Hex 


0000 = 0 
0001 = 1 
0010 = 2 
0011 = 3 

0100 = a 

0101 = 5 

0110 = 6 
0111 = 7 

1000 = 8 
1001 = 8 

1010 = A 

1011 = B 

1100 = C 

1101 = D 

1110 = E 

nil = F 


Figure 6-8 Converting the Shape Defini¬ 
tion to Hexadecimal 


The final step is to convert the binary codes representing the plotting 
vectors into hexadecimal form so you can type them into the com¬ 
puter. As shown in Table 6-3, each hexadecimal code corresponds to 
a group of four bits; so each row of eight bits in your definition table is 
represented by two such codes (called hexadecimal digits). This step 
is illustrated in Figure 6-8. The final shape definition for the shape in 
Figure 6-5 is 

12 3F 20 ea 2D 15 3B IE 07 00 

The Shape Table Index 

There is still a little more information you need to provide before you 
have a complete shape table: the table must have an index. This is 
simply a list indicating where in memory to find a particular shape. 
Applesoft needs the index so that it can find the shape later, when 
your program tries to draw the shape on the screen. 


Section: C B A 

byte 0 0 0 0 1 0 0 1 0 

1 0011 1111 

2 0 0 1 0 0 0 0 0 

3 0 1 1 0 0 1 0 0 

4 0 0 10 11 0 1 

5 0 0 0 1 0 1 0 1 

6 0 0 1 1 011 0 

7 0 0 0 1 111 0 

8 0 0 0 0 0 1 1 1 

9 0 0 0 0 0 0 0 0 

hex: digit 1 digit 2 



bytes 

recoded 



in hex 



1 2 



3 F 


= 

2 0 



G 4 



2 D 



1 5 



3 8 



1 E 



0 7 



0 0 ^ 

■denotes end 



of shape 
definition 


The form of a complete shape table, including the index, is shown in 
Figure 6-9. The shape table’s starting location, whose address is 
called S in the figure, contains the number of shape definitions in the 
table (between 00 and FF) in hexadecimal. The next byte (address 
S -1- 1) is unused; it is followed by a sequence of two-byte pairs 
giving the locations of the shapes in the table. (Notice that the shape 
locations are given with the bytes reversed—low-order byte first— 
and that the locations are specified relative to address S, the start of 
the table itself, and not in absolute memory addresses.) For simplic¬ 
ity, the shape definitions themselves are usually placed immediately 
after the index. 


Shape Tables 


153 















Figure 6-9 Form of a Complete Shape 
Table 


start = S 


index < 


shape 

definitions 


byte S 4- 0 

n(OtoFF) 

+ 1 

unused 

+ 2 

lower 2 digits 

+ 3 

upper 2 digits 

+ 4 

lower 2 digits 

+ 5 

upper 2 digits 

• 

• 

• • • 

• • • 

• • • 

-f- 2ri 

lower 2 digits 

\^+2n-l-1 

upper 2 digits 

^ S + Dl 


first byte 

• 

• 

• 

last byte = 0 0 



S + D2 

first byte 

• 

• 

• 

last byte = 00 

• 

• • 

• • 

• • 

8 + D fi 

first byte 

• 

• 

V • 

last byte = 00* 


total number of 
shape definitions 

D1: index to first byte of shape 
definition #1, relative to S 
D 2: index to first byte of shape 
definition #2, relative to S 


D n: index to first byte of shape 
definition #n, relative to S 


shape definition #1 


shape definition #2 


shape definition #n 


Figure 6-10 A Complete Shape Table 


start 

(store address 
in E8 and ES) 

1 

byte 0 
1 

2 
3 

a 

5 
G 

7 

8 
9 
A 
B 
C 
D 


01 

00 

04 

00 

12 

3F 

20 

64 

2D 

15 

38 

IE 

07 

00 


-number of shapes 

index to shape 
definition #1, 
relative to start 
first byte 


y shape definition #1 


last byte 


high-resolution graphics pages: see 

Sections 6.2.1,6.2.2 


Figure 6-10 shows the complete shape table for our example. Since 
there’s only one shape in the table, location S contains the value 1. 
Bytes S -I- 2 and S -I- 3 are needed to specify the shape’s lo¬ 
cation; the shape definition itself can start in the next available byte, S 
+ 4. So index byte S -I- 2 contains the value 0 4 and Index byte 
S -t- 3 contains the value 00. Next come the bytes of the shape 
definition, as derived in Figure 6-8. The table ends with the zero byte 
marking the end of the shape definition. 

Loading a Shape Table into Memory 

Now that you’ve figured out how to code your shape in the form of a 
shape table, you have to get It into the computer’s memory so Apple¬ 
soft can draw it on the screen. You also have to tell Applesoft where 
In memory to look for the shape table. 

First you must choose a starting address. This address must be less 
than the highest memory address available in your system, and must 
not be located in the high-resolution graphics page that you’ll be us¬ 
ing to display the shapes (locations 2 0 0 0 through 3 F F F for page 1, 
4000 through 5 F F F for page 2). For this example, we’ll use hexa¬ 
decimal address 1DFC, which is just below high-resolution page 1. 
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A 

Keep shape table out of harm’s way 


Apple He Monitor program : see Apple 
He Reference Manual 

D R A U statement: see Section 6.3.2 

POKE statement: see Section 7.1.2 


Warning 

Be sure you don’t place your shape table in an area that will conflict with 
your program or variable space, or with vital internal information used by 
the system. See the box labeled “Protecting Your Shape Table,” below, 
for information on how to keep your program and shape table out of each 
other’s way; see Appendix H for the memory locations of important sys¬ 
tem information. 


While you’re in the process of creating the shape table, you’ll proba¬ 
bly want to type the table into memory directly from the keyboard us¬ 
ing the Monitor program. Then you can draw the shape on the screen 
with an immediate-execution DRAW statement, see if it looks the way 
you want it, and go back and change it if it doesn’t. See your Apple He 
Reference Manual for information on the use of the Monitor program. 

Once your shape table looks correct, you’ll want to be able to use it 
from within a program. Your program can store the table into memory 
by using P 0 K E. To do this, you have to convert the starting address 
of the table, and each byte of the table itself, from hexadecimal to 
decimal, then store the decimal values into memory one at a time. 

The shape table we’ve been developing consists of the hexadecimal 
bytes 

01 00 04 00 12 3F 20 B4 2D 15 3B IE 07 
00 

The equivalent decimal values are 
1 040 18 B3 32 100 45 21 54 30 7 0 


The starting address we’ve chosen for the table, hexadecimal 1D F C, 
is equivalent to 7B7B decimal. So the following statements in apro- 
gram will store the shape table into memory; 


10 FOR X = 7B7B 


20 READ A 
30 POKE X» A 
40 NEXT X 
50 DATA 1 fO »4 »0 » 
54 »30 fl »0 


to 7B89 

—memory locations where 
shape table will go 
—read byte of table 
—store at next location 
—go back for next byte 
18 »B3 »32 »100 *45 *21 
—contents of table 


Shape Tables 









store the starting address of the shape 
table 


S H L 0 A D statement : see Section 6.3.2 

Protect your tables 

HIMEH: statement: see Section 7.2.1 


Another way for a program to store a shape table into memory is to load 
it from a disk or tape cassette. Details are given below under “Saving 
and Loading a Shape Table.” 

Now that you have your shape table in memory, you have to tell 
Applesoft where to find it. Applesoft looks for the table’s starting ad¬ 
dress in hexadecimal locations E8 (low-order byte) and E9 (high-or- 
der byte), so you have to arrange somehow to store the correct 
starting address into these locations. If you’ve been using the Monitor 
program to type the shape table into memory from the keyboard, you 
can type its address into locations E8 and E8 in the same way. From 
within a program, you can do it with two more POKE statements. The 
hexadecimal addresses E 8 and E 8 are equivalent to decimal 232 
and 2 3 3; the two bytes of the table’s starting address, 1D and F C, 
are equivalent to 28 and 252. So the following POKE statements 
will do the trick: 

BO POKE 232» 252 : POKE 233> 28 

Your shape table is now stored correctly in the computer’s memory, 
ready to be drawn on the screen from within your program with a 
DRAW statement. 

Remember to store the two bytes of the starting address in reverse or¬ 
der, with the low-order byte before the high-order byte. This convention 
is always followed when storing memory addresses in the Appie lie’s 
memory. 


When you use S H L 0 A D to load a shape table from a tape cassette, the 
starting address is set up for you automatically in the proper locations. 


Protecting Your Shape Table: In choosing a location in memory for 
your shape table, it’s important to keep it out of the way of your Applesoft 
program, so the two don’t ovenwrite each other. One way to do this is 
simply to use HIM E M : to set the upper limit of program memory to the 
starting address of the table. In the example, 

HIMEM: 7B7B 

This too is done automatically when you use S H L 0 A D to get the table 
from a tape cassette. 

Unfortunately, this method leaves very little room for your program and 
variables—in the example, only 5628 bytes (7B7B minus 20^8). You 
can buy a little more space for your program by setting HIMEM; to the 
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beginning of the graphics page you’re using (819 2 for page 1,18384 
for page 2), as suggested in Section 6.2.5, “Protecting High-Resolution 
Graphics.” You can then locate the shape table above the graphics 
page: that is, above location 1G 3 8 4 if you’re using page 1,2 45 7 G if 
you’re using page 2. 

Perhaps the best method is to locate the program and variables above 
the graphics page, again as described in Section 6.2.5. This leaves 
room for the shape table below the start of the graphics page. If you’re 
using graphics page 1, that’s6144 bytes (8192 minus 2048)— 
enough room for a very extensive shape table! 

Don’t overwrite DOS! 

Warning 

If you locate your shape table above the high-resolution graphics page 
and your system is equipped with one or more disk drives, be careful not 
to run into the memory space occupied by the Disk Operating System, 
beginning at location 38400 (hexadecimal 9GOO). 

Saving a shape table on a disk 

Saving and Loading a Shape Tabie 

To save your shape table on a disk, you need to know two things: 

• The starting address of the table (1D F C in the example) 

• The length of the table in bytes (14 in the example—hexadecimal 
0 0 0 E—including the “stop” byte) 

Next, you must choose a file name under which to store your shape 
table on the disk. We’ll use S H A P E1 for this example. 

DOS: Disk Operating System 

To save the table on a disk in immediate execution, put the disk in the 
disk drive and issue the following DOS command: 

B S A U E command : see DOS manual 

BSAME SHAPEl» A$1DFC» L$000E 

binary file: a file containing “raw” infor¬ 
mation not expressed in text form 

This command says “store a binary file named S H A P E1 on the disk, 
containing the current contents of memory starting at hexadecimal 
address 1DFC, and OOOE (hexadecimal) bytes long.” 

If you’re using a disk drive other than the main startup drive, the B 9 A M E 
command should also include slot and drive parameters specifying 
which disk drive to use; see your DOS manual for details. 

To issue the same command from within an Applesoft program, use 
the statement 

PRINT CHR$ (4)5 "BSAME SHAPEl» A$1DFC» 
L$000E" 
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Again, see your DOS manual for details. 


Loading a shape table from a disk 

BLO AD command: see DOS manual 


Don’t forget the starting address 


Saving a shape table on tape 


Apple lie Monitor program: see Apple 
He Reference Manual 


Loading a shape table from tape 

S HL 0 A D statement: see Section 6.3.2 


To load the table back into memory from the disk, you can use the 
DOS command 

BLOAD SHAPEl 

in immediate execution, or the statement 

PRINT CHR$ (4); "BLOAD SHAPEl" 

from within a program. Notice that you don’t have to include the start¬ 
ing address and the table length; this information will be picked up 
automatically from within the disk file itself. However, the starting ad¬ 
dress is not stored automatically into the special addresses where 
Applesoft looks for them, so you (or your program) will have to do that 
for yourself: 

POKE 232» 252 ; POKE 233* 23 

To save your shape table on a tape cassette, you need to know three 
things: 

• The starting address of the table (1D F C in the example) 

• The last address of the table (1E 0 9 in the example) 

• The difference between the first two items (hexadecimal 0 0 0 D, 
decimal 14) 

Item 3, the difference between the last address and the first address 
of the table, must be stored in locations 0 (low-order byte) and 1 
(high-order byte). From the Monitor, type 

0:0D 00 

and press I return I . Now you must write to the cassette first the ta¬ 
ble length from locations 0 to 1, then the shape table itself: 

O.IW 1DFC.1E09W 

Don’t press the | return | key until you’ve put a cassette in your tape re¬ 
corder, rewound it, and started it recording. 

To load the shape table back from the tape, use the S H L 0 A D 
statement. 
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I CONTROL l -C: see Section 1.3.2 


6 . 3.2 Using Shape Tables 

The commands in this section are used to draw and manipulate on 
the screen shapes defined by a shape table in memory: 

• DRAW and X D R A W draw shapes from a shape table onto the 
high-resolution screen. 

• S C A L E = controls the scale at which shapes are drawn on the 
screen. 

• R 0 T = controls the rotation of shapes on the screen. 

• SHLOAD loads a shape table into memory from a tape cassette. 

As a preview of what the commands in this section can do, here’s a 
sample Applesoft program for you to try. The program first stores Into 
memory the shape table developed in Section 6.3.1, using the P 0 K E 
statement (see “Loading a Shape Table into Memory).” Then it uses 
the statements described in this section to produce a somewhat sur¬ 
prising effect on the screen. See if you can guess what the program 
will display, then type it and run it: 


10 

FOR X = 7G7G TO 

7G89 



—memory locations where 



shape table will go 

20 

READ A 

—read byte of table 

30 

POKE X» A 

—store at next location 

40 

NEXT X 

—go back for next byte 

50 

DATA 1 »0 »4 »0 »18 j 

G3 »32 »100 »45 »21 » 


54 »30 tl »0 

—contents of table 

100 

HGR2 


110 

HC0L0R= 3 


120 

FOR R = 1 TO 50 


130 

R0T= R 


140 

SCALE- R 


150 

XDRAW 1 AT 140» 

3G 

IBO 

NEXT R 


170 

GOTO 120 



When you get tired of watching the show, interrupt the program by 
pressing | control | -C to regain control of the system. 
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The DRAM Statement 

DRAW 5 

DRAW 1 AT lUOf 3B 

DRAW SHAPE AT XCENTER + XOFFSET » 
YCENTER + YOFFSET 

D R A N draws a shape on the high- 
resolution screen 

The DRAW statement draws a shape from a shape table on the high- 
resolution graphics screen at a specified location. The expression 
following the keyword DRAW gives the index number of the desired 

shape tables: see Section 6.3.1 

shape within the shape table currently in memory. The location at 
which the shape is to be drawn is specified by a pair of expressions 
following the keyword AT, separated by a comma. The first expres¬ 
sion gives the horizontal screen position of the shape’s starting point; 
the second gives the vertical position. 

H C 0 L 0 R = statement: see Section 

6.2.3 

The designated shape is drawn in the current display color, scale, 
and rotation, as specified in the most recently executed HCOLOR = , 
SCALE = , and ROT = statements. 

▲ 

Warning 

You must specify the color, scale, and rotation of the shape before 

DRAW is executed. If any of these have not been specified, the results 
will be random: odd dots may appear, bizarre shapes may be drawn, 
and memory may be overwritten. 


Assuming that a shape table is already loaded into memory (see 
“Loading a Shape Table into Memory” in Section 6.3.1 ), the following 
program will draw the first shape in the table at column 50, row 100: 

10 H G R — display high-resolution 

graphics 

20 HC0L0R= 3 —set color to white-1 

30 ROT = 0 — orient shape as originally 

defined 

40 SCALE= 5 —enlarge shape 5 times 

50 DRAW 1 AT 50 » 100 — draw shape 1 at column 50, 

row 100 

If you omit the keyword A T and the screen coordinates, 

50 DRAW 1 
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H P L 0T statement: see Section 6.2.4 
X D R A W statement: see below 


Applesoft will put the shape on the screen starting at the last point 
plotted by the most recently executed HPLOT,DRAW,or K DRAW 
statement. (The shape drawn on the screen may not actually begin at 
the last point previously plotted. If the first plotting vector in the shape 
doesn’t actually plot a point, there will be an offset between the first 
visible point in the shape and the last point plotted.) If no such state¬ 
ment has been executed, the results are unpredictable. 


If the shape number specified is less than 0 or greater than the actual 
number of shapes in the shape table, the program will halt with the 
message 

7ILLEGAL QUANTITY ERROR 


Be sure to load a shape table first 


I CONTROL | - | RESET See Section 1.3.2 


HGR statement: see Section 6.2.1 


Warning 

If you execute DRAW without first loading a shape table into memory, the 
system may hang (use | control | - | reset | to recover), or Applesoft 
may draw random shapes anywhere in the high-resolution graphics 
area of memory (locations 8192 to 24575 decimal), whether or not 
HGRorHGR2 has previously been executed. This can have disastrous 
consequences if your program is longer than about 6000 bytes. 


The XDRAW Statement 
XDRAW 5 

XDRAW 1 AT 140r 80 

XDRAW SHAPE AT XCENTER + XOFFSET» 
YCENTER -h YOFFSET 


XDRAW erases a shape The XDRAW statement works exactly the same as D R A W, except 

that the color used to draw the shape is the complement of the color 
already existing at each point plotted. The following pairs of colors 
are complements: 

Complementary colors • black and white 

• violet and green 

• blue and orange 

X D R A W is most commonly used to erase a previously drawn shape. 
The following program, which assumes that a shape table has al¬ 
ready been loaded into memory (see “Loading a Shape Table into 
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Memory” in Section 6.3.1), illustrates the point by drawing and then 
erasing the same shape, leaving the screen blank: 


10 

HGR2 



20 

HC0L0R= 

= 3 


30 

R0T= 0 



40 

SCALED 

5 


50 

DRAW 1 

AT 

50 ♦ 

BO 

FOR Z = 

= 1 

TO 

70 

XDRAW 1 

AT 

50 


—display full-screen high-reso- 
lution graphics 
—set color to white-1 
—orient shape as originally 
defined 

—enlarge shape 5 times 
—draw shape at column 150, 
row 100 
1 NEXT Z 


—stall for a short time 
10 0 —erase the shape 


If you use D R A W and X D R A W alternately in a loop, you can do 
animation: 


10 

HGR2 



20 

HC0L0R= 

= 4 


30 

R0T= 0 



40 

SCALE = 

5 


50 

FOR X = 

= 1 

TO 200 

GO 

DRAW 1 

AT 

50 + X* 

70 

XDRAW 1 

AT 

50 4- X 

80 

NEXT X 




—display full-screen high-resolU' 
tion graphics 
—set color to white-1 
—orient shape as originaily 
defined 

—enlarge shape 5 times 
—loop 200 times 

too 

—draw shape in a different col¬ 
umn each time 

too 

— erase shape 
—repeat loop 


If the shape number specified is less than 0 or greater than the actual 
number of shapes in the shape table, the program will halt with the 
message 

?ILLEGAL QUANTITY ERROR 


Be sure to load a shape table first Warning 

If you execute X D R A W without first loading a shape table into memory, 

I CONTROL I - IresetI : see Section 1.3.2 the system may hang (use | control | - |reset| to recover), or Applesoft 

may draw random shapes anywhere in the high-resolution graphics 
area of memory (locations 8192to2d575 decimal), whether or not 
HGR statement: see Section 6.2.1 HGRorHGR2 has previously been executed. This can have disastrous 

consequences if your program is longer than about 6000 bytes. 
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The SCALE = Statement 


S C A L E = sets scale factor for D R A N 

andXDRAN 

ORAN and X D R A N statements: see 
above 


SCALE= 10 
scALE= z / a 


The S C A L E = statement sets the scale factor (relative size) for the 
high-resolution graphics shape to be drawn by D R A W or X D R A W. 
The expression following the keyword S C A L E = specifies the scale 
factor, which may range from 1 (reproduce the shape exactly as orig¬ 
inally defined) up to a maximum of 2 5 5 (draw the shape 255 times 
the size originally defined). 

Assuming that a shape table is already loaded into memory (see 
“Loading a Shape Table into Memory” in Section 6.3.1), the following 
program will draw the first shape in the table at three different posi¬ 
tions on the screen and in three different sizes: 


10 

HGR2 


—display full-screen high-reso¬ 
lution graphics 

20 

HC0L0R= 3 


—set color to white-1 

30 

ROT- 0 


—orient shape as defined 

40 

SCALE- 1 


—use original size 

50 

DRAW 1 AT 

100 t 

100 —draw shape at column 100, 
row 100 

GO 

SCALE- 2 


—scale to twice original size 

70 

DRAW 1 AT 

150 ♦ 

100 —draw at column 150, row 100 

80 

SCALE- 3 


—scale to three times size 

90 

DRAW 1 AT 

200 t 

10 0 —draw at column 200, row 100 


A scale setting of 0 is considered equivalent to the maximum setting 
(255). If the scale setting specified is less than 0 or greater than 2 55, the 
program will halt with the message 

?ILLEGAL QUANTITY ERROR 


Scale factors are useful only up to a certain point. Large scale settings 
produce some rather outlandish results on the screen. 


Notice that the equal sign is part of the keyword S C A L E =; it doesn’t 
represent an assignment to a variable named S C A L E. A statement 
such as 

LET SCALE= X 

will cause a syntax error. The only way to find out the current scale 
setting is to keep track of it yourself with a separate variable. 
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The ROT = Statement 


R 0 T = sets rotation for D R A W and 

XDRAW 

DRAWandXDRAW statements: see 
above 


Rotation aiso depends on scaie 
setting 

scaie setting: see above 


ROT= IB 

ROT= 32 + 2 * R 


The R 0 T = (for “rotation”) statement sets the angular rotation for the 
high-resolution graphics shape to be drawn by D R A W or X D R A W. 
The expression following the keyword ROT = specifies the rotation 
in units of 5.625 degrees (1 /64 of a circle). R 0 T = 0 will orient the 
shape exactly as defined in the shape table, R 0 T = 1B will rotate 
the shape 90 degrees clockwise, R 0 T = 3 2 will rotate it 180 de¬ 
grees, and so on. The process repeats starting at ROT = G4. 

Assuming that a shape table is already loaded into memory (see 
“Loading a Shape Table into Memory” in Section 6.3.1), the following 
program will draw the first shape in the table, five times its original 
size, at two different positions on the screen, once oriented as origi¬ 
nally defined and once rotated by 45 degrees: 


10 

HGR2 


20 

HC0L0R= 

30 

SCALE 

= 

40 

R0T = 

0 

50 

DRAW 

1 

GO 

R0T = 

8 

70 

DRAW 

1 


: 3 
5 

AT 50f 100 

AT 100» 100 


—Display full-screen high-reso- 
lution graphics 
—set color to white-1 
—scale shape to five times origi¬ 
nal size 

—orient shape as originally 
defined 

—draw shape at column 50, row 
100 

—rotate shape 45 degrees 
—draw shape at column 100, 
row 100 


The amount of rotation obtainable is somewhat dependent on the 
current scale setting. For S C A L E = 1, Applesoft recognizes only 
four rotation values (0, IB, 32, 48); for SCALE = 2, it recognizes 
eight rotation values (0, 8, lG,...);forSCALE= 3, it recognizes 
twelve rotation values; and so on. For scale settings of 1G or more, 
the full range of rotation values is avaiiable. For unrecognized rota¬ 
tion values, Applesoft usually orients the shape with the next smallest 
rotation that it recognizes. 
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SHLOAD 

tape 

HIMEMs 


Notice that the equal sign is part of the keyword R 0 T =; it doesn’t repre¬ 
sent an assignment to a variable named R 0 T. A statement such as 

LET ROT= X 

will cause a syntax error. The only way to find out the current rotation 
setting is to keep track of it yourself with a separate variable. 


If the rotation setting specified is less than 0 or greater than 255, the 
program will halt with the message 

7ILLEGAL QUANTITY ERROR 

The SHLOAD Statement 
SHLOAD 


loads a shape table from The SHLOAD statement (for “shape load”) loads a shape table from 

a tape cassette. The shape table is loaded just below the upper limit 
statement; see Section 7.2.1 of available program and variable space (HIMEM:):HIMEH;is 

then set just below the shape table to protect it. 

To use S H L 0 A D in immediate execution, turn on your tape recorder 
with the proper tape inserted and cued up to the proper place. Then 
type 

SHLOAD 

and press I return | . You should hear one “beep” when the shape 
table’s length has been read successfully, and another when the ta¬ 
ble itself has been read. 

You can also use SHLOAD from within a program (with appropriate 
prompting messages) to allow users to load their own shape tables: 

100 PRINT "CUE UP YOUR SHAPE TAPE AND 
PRESS THE PLAY BUTTON." 
no PRINT "THEN PRESS THE RETURN KEY TO 
LOAD THE SHAPE TABLE." 

—prompt user with instructions 
120 GET STALL$ —wait for keypress 

130 SHLOAD —load shape table from tape 

140 PRINT "TABLE LOADED—PLEASE SHUT OFF 
YOUR RECORDER." —tell user table is loaded 
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Don’t forget to turn on your tape recorder! 
I CONTROL | - |reset| : see Section 1.3.2 


For more information... 


If you load a second shape table replacing the first one, you or your pro¬ 
gram should reset HIM E M; to avoid wasting memory. See the section 
“Loading a Shape Table into Memory” in Section 6.3.1 for more informa¬ 
tion on shape tables and memory usage. 


If you try to use S H L 0 A D without a tape recorder connected, 
turned on, and set to play, the system will hang indefinitely. Use 
I CONTROL | - | RESET | to regain control. 


If a variable name begins with the reserved word S H L 0 A D 
SHLOADER = 59 

S H L 0 A D may be executed before a syntax error is detected. In such a 
case, the system will patiently wait (forever, if nec essary) for a shape t a- 
ble to be loaded from a tape cassette. Again, use | control [ - 1 reset | to 
recover. 


For information on saving a shape table on tape, see “Saving and Load¬ 
ing a Shape Table” in Section 6.3.1. See Appendix M for a list of all 
statements dealing with tape cassettes. 
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Chapter 7 


direct memory access: see Section 7.1 


memory management: see Section 72 


debugging: see Section 73 



7.1 


PEEK function : see Section 71.1 
POKE statement: see Section 71.2 
CALL statement: see Section 71.3 
U S R function : see Section 71.4 
WAIT statement: see Section 71.5 


utility Statements 


The features covered in this chapter are concerned with low-level 
control of the programming environment. 

Section 7.1, “System Utilities,” discusses direct access to specific lo¬ 
cations in the computer’s memory from within an Applesoft program. 

Section 7.2, “Memory Management,” describes the ways in which 
Applesoft programs can control the limits of program space. 

Section 7.3, “Debugging,” tells how to trace the execution of a run¬ 
ning program for debugging purposes. 

System Utilities 

This section describes statements and functions that give Applesoft 
programs direct access to the Apple lie’s memory: 

• PEEK examines the contents of a memory location. 

• POKE alters the contents of a memory location. 

• CALL and U S R allow Applesoft programs to execute machine- 
language subroutines stored in the computer’s memory. 

• WAIT suspends program execution until a specified signal is 
received from a peripheral device. 
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7.1.1 


The PEEK Function 


PEEK examines contents of a mem¬ 
ory location 


Certain locations hold special informa¬ 
tion or produce special effects: see 
Appendix F 


7.1.2 


POKE alters contents of a memory 
location 


The PEEK function directly examines the contents of a specified lo¬ 
cation in the computer’s memory. The argument given to P E E K is the 
decimal address of the desired memory location. PEEK yields the 
contents of the specified location, which will be an integer from 0 to 
2 5 5. For example, the following program displays the contents of 
addresses 100 through 120: 

10 FOR ADDR = 100 

TO 120 —loop through desired 

addresses 

20 PRINT "LOCATION ADDR5 "HOLDS THE 
MALUE "5 PEEK (ADDR) 30 NEXT ADDR 

—display contents of location 
—go back for next address 

Certain locations in the Apple lie’s memory hold special system infor¬ 
mation or produce special effects whenever their contents are read. 
One important use of P E E K is for manipulating these special loca¬ 
tions. See Appendix F, “Peeks, Pokes, and Calls,” for details. 


If P E E K is given a negative argument value, it adds G 55 3 B (2 to the 
16th power) to obtain an equivalent positive address. For exampie. 


PEEK (-lG38a) 
PEEK (-1) 

PEEK (-327B8) 
PEEK (-G5500) 


is equivalent to PEEK 
is equivalent to PEEK 
is equivalent to PEEK 
is equivalent to PEEK 


(49152) 

(G5535) 

(327G8) 

(3G) 


If the argument is not in the range - B5535to+B5535>the pro¬ 
gram will halt with the message 

7ILLEGAL QUANTITY ERROR 


The POKE Statement 

POKE 34* 8 
POKE -1B302» 0 

POKE ADDR» (2*D1 + 3*D2) / (U - M) 


The POKE statement stores a specified value directly into a location 
in the computer’s memory. The first expression following the keyword 
POKE gives the decimal address of the memory location; the second 
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A 


I CONTROL H RESET | : see Section 1.3.2 


7.1.3 


CALL executes a machine-language 
subroutine 


expression, separated from the first by a comma, gives the value to 
be stored into that location. For example, 

POKE 3 4 * 8 —stores value 8 into location 

34 


Warning 

Be certain that the address into which you are storing doesn’t contain 
part of your program or some vital system information that you don’t 
want to change. An ill-advised POKE can hang the system, drop you 
into the Monitor, or alter the operation of the system or of your program in 
unpredictable and possibly disastrous ways. In the event of catastrophe, 
use I CONTROL I - | RESET | to regain control of the system. See Appendix 
H for the locations of vital system information that shouldn’t be tampered 
with. 


Certain locations in the Apple lie’s memory hold special system infor¬ 
mation or produce special effects whenever a value is stored into 
them. One important use of P 0 K E is for manipulating these special 
locations. See Appendix F, “Peeks, Pokes, and Calls,” for details. 

If P 0 K E is given a negative target address, it adds B 5 5 3 S (2 to the 
16th power) to obtain an equivalent positive address. For example, 

POKE ~1G384# 0 is equivalent to POKE 49152 . 0 

POKE -32768 f 112 is equivalent to POKE 32788. 

112 

POKE -S5502. 8 is equivalent to POKE 34. 8 

If the target address is not in the range - 6 5 5 3 5 to + 6 55 3 5, or if the 
specified value is not in the range 0 to 2 5 5, the program will halt with 
the message 

7ILLEGAL QUANTITY ERROR 


The CALL Statement 

CALL 54315 
CALL -93S 
CALL ROUTINE (J) 


The CALL statement executes a machine-language subroutine from 
within an Applesoft program. The decimal address of the desired 
subroutine follows the keyword CALL. Control is transferred to the 
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subroutine at the designated address; when the subroutine is fin¬ 
ished, execution continues with the statement following the CALL. 

For example, 

CALL G4BB8 — executes machine-language 

subroutine beginning at ad¬ 
dress B4BB8 

▲ 

Warning 

1 CONTROL |-| RESET |: 866 S6Ction 1.3.2 

Make sure the address you give in the CALL statement is the beginning 
of a valid machine-language subroutine! A misdirected CALL can have 
unpredictable and probably unpleasant consequences, such as hang¬ 
ing the system or dropping you into the Monitor. If any of these calamities 
befall you, use 1 CONTROL H reset [to regain control of the system. 

system calls: S66 Appsndix F 

The Apple lie’s buiit-in firmware contains many useful subroutines 
accessible with the CALL statement; see Appendix F, “Peeks, 

Pokes, and Calls,” for details. 

POKE statement: see Section 7.1.2 

You can also use CALL to execute machine-language subroutines 
of your own, which you have stored into memory with the P 0 K E 

Apple Me Monitor program: see Apple 

He Reference Manual 

statement, typed from the keyboard via the Monitor, or loaded into 
the computer from a disk or tape. 

If CALL is given a negative target address, it adds S553B (2 to the 

16th power) to obtain an equivalent positive address. For example, 

CALL -936 is equivalent to CALL G4S00 

CALL -BBS is equivalent to CALL B4GB8 

CALL -1998 is equivalent to CALL 63538 

If the target address is not in the range - G 5 53 5 to -l- B55 35, the 
program will halt with the message 

7ILLEGAL QUANTITY ERROR 

7.1.4 

The USR Function 

Not for Everyone: This feature is intended for expert programmers 
only, and requires a knowledge of machine-language programming. 

Readers with fewer than sixteen fingers are advised to skip this section. 

USR executes a machine-language 
function routine 

The USR (for “user-supplied routine”) function executes a machine- 
language function routine stored into the computer’s memory by you, 
the user. Such a routine typically performs some high-speed compu¬ 
tation that cannot be done efficiently, or cannot be expressed at all, in 
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Applesoft. The argument supplied to the U S R function is passed un¬ 
changed to the machine-language routine, and the result yielded by 
the routine is passed back as the value of the U S R call. 


POKE statement: see Section 7.1.2 

Apple lie Monitor program: see Apple 
He Reference Manual 


Argument and result passed via floating¬ 
point accumulator 


The function routine to be executed with U S R may be stored into the 
computer’s memory with the POK E statement, typed from the key¬ 
board via the Monitor, or loaded into the computer from a disk or tape. 
When U S R is called, the value supplied as an argument is placed 
into the floating-point accumulator in the computer’s memory (hexa¬ 
decimal locations $9D to $ A3); control is then transferred via 
a machine-language JSR (Jump to Subroutine) instruction to 
hexadecimal address $0A (decimal 10). Locations $0A to $0C 
(decimal 10 to 12) must contain a machine-language JM P (Jump) 
instruction to the beginning of the machine-language routine. The 
routine should leave its result in the floating-point accumulator and 
return control to Applesoft with an R T S (Return from Subroutine) in¬ 
struction. The contents of the floating-point accumulator are then 
passed back to your Applesoft program as the value yielded by U S R. 


Here is a trivial example showing the use of the U S R function. The 
machine-language routine shown here simply takes the argument 
value it receives and multiplies it by 8; 


] CALL -151 —leave Applesoft: enter Monitor 

* 0A:4C 00 03 —set up machine-language 

jump to hexadecimal address 
$300 

* 0300:18 A5 9D 89 03 85 3D 80 

—enter short machine-language 
routine to multiply contents of 
floating-point accumulator by 
8 

* I CONTROL I - C —return to Applesoft 

] PRINT USR (3) —execute routine with argument 

value 3 

2 4 —result displayed on screen 


Locations $0 A to $0C must contain a 
J M P to the routine 


At hexadecimal address $ 0 A, there is a J M P (op code 4 C) to hex¬ 
adecimal address $300. (As usual in 6502 machine language, the 
low-order byte of the address, 0 0, precedes the high-order byte, 

03.) Beginning at address $300 is a machine-language routine to 
multiply the value in the floating-point accumulator by 8. Back in 
Applesoft, when the function call U 8 R ( 3 ) is executed, the argu¬ 
ment value 3 is placed in the floating-point accumulator and control is 
passed to the machine-language routine via the J M P at location 
$ 0 A. The machine-language routine gets the value in the floating- 
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7.1.5 


Novices need not apply 


N AIT waits for a signal from a periph¬ 
eral device 


mask: a pattern of bits for use in bit-level 
logical operations 


point accumulator, multiplies it by 8, puts the result (24) back into the 
floating-point accumulator, and returns control to Applesoft with an 
RTS instruction (op code GO). The value 24 is then passed back as 
the result of the U S R call. 

To obtain a two-byte integer from the value in the floating-point accumu¬ 
lator, your machine-language routine should do a J S R to address 
$ E 01C. Upon return, the integer value will be in locations $ A 0 (high- 
order byte) and $A 1 (low-orderbyte). 

To convert an integer result to its floating-point equivalent, so that the 
function can return that value, place the two-byte integer in registers A 
(high-order byte) and Y (low-order byte). Then do a JSR to address 
$ E 2F2. Upon return, the floating-point value will be in the floating-point 
accumulator. 


The N AIT Statement 

WAIT a03a7» 15 
WAIT 40401 » 240 » 102 
WAIT ADDRXj hilt M2% 


For Experts Only: This feature is intended for expert programmers 
only, and requires an understanding of bit-masking operations. If you 
think a mask is something you wear on Halloween, you can safely afford 
to skip this section. You won’t miss a thing. 

The WAIT statement suspends program execution until a specified 
bit pattern appears at a specified memory location. It is typically used 
to wait for a particular status signal from a peripheral device. 

The first expression following the keyword WAIT designates the ad¬ 
dress of the memory location to be tested. The second expression 
represents a one-byte mask specifying which bits of the designated 
location are of interest: a one bit in the mask means that the corre¬ 
sponding bit of the memory location is to be tested; a zero bit means 
it is to be ignored. The optional third expression is another one-byte 
mask specifying the bit value to be tested for in each position of the 
memory location: a one bit in the mask tests for a zero bit in the corre¬ 
sponding position of the memory location, and vice-versa (!). If the 
second mask is omitted, all bit positions specified by the first mask 
will be tested for a one bit. For example. 
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WAIT 

ADDR » 

255 


—wait for a one bit anywhere In 
location ADDR 

WAIT 

ADDR ♦ 

255 » 

255 

—wait for a zero bit anywhere in 
location ADDR 

WAIT 

ADDR » 

1 


—wait for low-order bit of loca¬ 
tion A D D R to become 1 

WAIT 

ADDR ♦ 

128 » 

128 

—wait for high-order bit of loca¬ 
tion A D D R to become 0 

WAIT 

ADDR » 

3 » 2 


—wait for low-order bit of loca¬ 
tion ADDR to become 1 or 
second low-order bit to be¬ 
come 0 


When W AIT is executed, the contents of the location specified by 
the first expression are exclusive-or’ed with the mask represented by 
the third expression (if any); the result is then anded with the mask 
represented by the second expression. If the result Is nonzero (that 
is, if any of the bits of interest are in the specified state), then program 
execution proceeds; if the result is zero (none of the bits of interest 
are in the specified state), then the test is repeated. Thus program 
execution will be suspended until one of the specified bits is set to the 
specified state by an outside agency (presumably a signal from a pe¬ 
ripheral device). 


A 


CONTROL I - |RE5ET| : SGG SGCtion 1.3.2 


Warning 

If the specified bit pattern never appears, program execution will hang 
forever. Make sure that the memory location you’re testing is receiving 
information th at will even t ually tes t true. The only way to interrupt a 
WAIT is with | control | - |re5et| . 


If W AIT is given a negative target address, it adds G 5 5 3 6 (2 to the 
16th power) to obtain an equivalent positive address. For example, 

WAIT -16189 t 15 is equivalent to WAIT 49347# 15 

If the target address is not in the range - G5535to+B5535,orlf 
either of the masks is not in the range 0 to 2 5 5, the program will halt 
with the message 

?ILLEGAL QUANTITY ERROR 
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7.2 

Memory Management 

The features discussed in this section are used to control the way 

Applesoft allocates memory space for your program: 

HI MEM : statement: see Section 7.2.1 

• The HIM E H: statement sets the upper limit of available pro¬ 
gram memory. 

L 0 M EM : statement: see Section 7.2.2 

• The L 0 M E M: statement sets the lower limit of available program 
memory. 

F R E function : see Section 7.2.3 

• The F R E function determines the amount of remaining memory 

space available to the program. ■ 

7.2.1 

r/ie HI MEM 5 Statement 

HIMEM: 8192 

HIM E M : sets upper limit of available 
program memory 

The HIMEM: statement sets the highest memory address available 
to an Applesoft program for storage of program lines and variables. 

The upper limit of available program memory is set to the value of the 
expression following the keyword HIMEM:. The area above this ad¬ 
dress is available for use by the Disk Operating System, high-resolu¬ 
tion graphics, or machine-language programs. 

Notice that the colon is part of the keyword HIMEM: and is required. 

Loading DOS resets HI MEM : 

Applesoft automatically sets HIMEM: to the address of the highest 
writable memory (RAM) address available on your computer. On sys¬ 
tems equipped with disk drives, loading the Disk Operating System 
(DOS) will automatically reset HIMEM: to a lower value in order to 
protect the area of memory occupied by DOS itself. See your DOS 
manual for further information. 

You can change the setting of HIM E M : only by 

Apple lie Monitor program: see Apple 

He Reference Manual 

• executing the HIM E M : statement 

• typing | control |-B to the Monitor program 

• restarting the system 

• loading a machine-language program 

A word to the wise 

Warning 

Resetting HIMEM: above its current value is an extremely dangerous 
practice that can result in writing over the Disk Operating System or 
other vital system information. Wise programmers will carefully investi¬ 
gate reserved memory areas before writing to them. 
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PEEK function: see Section 7.1.1 


7.2.2 

L 0 N E M : sets lower limit of available 
program memory 


D E F F N statement: see Section 2.4.3 


Adding a program line resets 

LOMEM: 

NEW command: see Section 1.2.1 


A common use of HIM E M s is to protect your program and high-resolu- 
tion graphics from overwriting each other. See Section 6.2.5, “Protecting 
High-Resolution Graphics,” for details. 


Helpful Hint: The current value of HIM E M: is stored in decimal mem¬ 
ory locations 115 and 11G; to obtain that value, use the expression 

PEEK (116) * 256 + PEEK (115) 


If HIM E M: is given a negative address, it adds 6 5 5 3 6 (2 to the 16th 
power) to obtain an equivalent positive address. For example, 

HIMEM: -57344 is equivalent to HIMEMs 8192 

If the specified address Is not in the range - 65535 to 4-65535, the 
program will halt with the message 

?ILLEGAL QUANTITY ERROR 

If the specified address is lower than the current setting of L 0 H E M :, or 
doesn’t allow enough room for the program already in memory, the pro¬ 
gram will halt with the message 

?OUT OF MEMORY ERROR 


The LOHEM: Statement 

LOMEM; 24576 


The LOMEM: statement sets the lowest memory address available 
to an Applesoft program for storage of variables. The lower limit of 
available program memory is set to the value of the expression fol¬ 
lowing the keyword LOMEM :. The area below this address is avail¬ 
able for high-resolution graphics or machine-language programs. 
LOMEM; also resets all variables to their initial values and wipes out 
all functions defined with DEF FN. 

Notice that the colon is part of the keyword LOMEM; and is required. 

Applesoft ordinarily begins to store variables at the end of the pro¬ 
gram in memory. Each time you add, delete, or change a program 
line, Applesoft resets LOMEM; to a location just above the final line 
of the program. Executing the NEW command or typing | control | -B 
to the Monitor resets LOMEM ; to its initial value. 
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The value of LOME M : can only be increased from its current setting. 
An attempt to set L 0 M E M ; to a lower value than the one already in 
effect will halt the program with the message 

?OUT OF MEMORY ERROR 



Don’t execute L 0 M E M : from within a 
program 


Warning 

Changing L 0 M E M s during the course of a program is a most danger¬ 
ous practice that can cause portions of the program or of Applesoft’s in¬ 
ternal control information to become unavailable, which in turn will 
cause the program to behave in outlandish ways (if at all). Programmers 
who behave with such reckless abandon have only themselves to 
blame. 


Helpful Hint: The current value of L 0 M E M : is stored in decimal mem¬ 
ory locations 105 and IDS; to obtain that value, use the expression 

PEEK function: see Section 7.1.1 PEEK (lOG) * 25G + PEEK (105) 


HI MEM : statement: see Section 7.2.1 


F R E yieids amount of avaiiabie mem¬ 
ory 


If L 0 H E M 5 is given a negative address, it adds 6 5 5 3 6 (2 to the 16th 
power) to obtain an equivalent positive address. For example, 

LOMEM: -49152 is equivalent to LOMEMs 16384 

If the specified address is not in the range - G5535to+B5535,the 
program will halt with the message 

?ILLEGAL QUANTITY ERROR 

If the specified address is higher than the current setting of HIM E N:, 
or lower than the address of the highest memory location occupied by 
the current operating system (plus any currently stored program), the 
program will halt with the message 

?0UT OF MEMORY ERROR 


7.2.3 The F R E Function 


The F R E function yields the number of bytes of unused writable 
(RAM) memory available to the running program. For example, 

LET AVAIL = FRE(O) —set A M AIL to amount of 

available memory remaining 

Notice that the name of the function is F R E, not F R E E. 
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HI MEM : statement: see Section 7.2.1 


Argument required but ignored 


If the number of free bytes exceeds 32767, F R E yields a negative re 
suit; adding B 5 5 3 G will give you the actual number of free bytes: 

IF FRE(O) < 0 THEN AVAIL = FRE(O) + 
G553B 

If you have set HIM E M s beyond the highest RAM address in your 
Apple lie, F R E may yield a value higher than the computer’s actual 
memory capacity. The reliability of such a value is to be taken lightly. 


Stranger Than Fiction: The argument given to F R E is ignored, and 
has no effect on the operation of the function. However, you can’t leave it 
out—you must include an argument expression of some kind to “keep 
the parentheses apart.” What you use for an argument expression 
doesn’t matter, but if Applesoft can’t evaluate it as a legal expression, 
you’ll get an error halt. 


How Applesoft Manages Free Space: The amount of free space re¬ 
ported by F R E is the number of b^es remaining below the string stor¬ 
age space and above the numeric array and string pointer array space 
(see Section H.2, “Applesoft Memory Allocation”). When Applesoft 
changes the contents of a string variable during the course of a program 
(say from ” C A T " to " D 0 G “), the characters In the old string 
(" C A T ") are not erased from memory; Applesoft simply allocates 
some fresh space to hold the new string (“ D 0 G"). As a result, charac¬ 
ters left over from unused strings take up “dead space” and slowly fill 
memory from HI M E M : down toward the top of the array space. 

Applesoft will automatically clear out these leftover characters when the 
bottom of string space “collides” with the top of array space. But if you’re 
using any of the free space for machine-language programs or for high- 
resolution graphics, they may be overwritten. 


Light Housecleaning: The automatic “housecleaning” just described 
takes time (anywhere from a fraction of a second to over two minutes, 
depending on the number of string variables your program is using). Fur¬ 
thermore, such housecleaning occurs at unpredictable moments— 
whenever your string and array spaces happen to collide. If it happens 
while Applesoft Is In the middle of displaying a message on the screen, 
for instance, It can cause unfortunate confusion for your program’s user, 
who will be left waiting for the computer to finish displaying a half-deliv¬ 
ered message. 

The F R E function provides a tool for warning the user that the computer 
will be busy for a while. The address of the current beginning of string 
space is kept In locations ill and 112 of the computer’s memory; the 
end of array space is kept in locations 10 9 and 110. Whenever Apple¬ 
soft needs to allocate more memory. It compares the contents of these 
locations; if they differ by less than one, Applesoft does its automatic 
housecleaning. 
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7.3 


7.3.1 


TRACE displays line numbers as they 
are executed 



CONTROL | -C:seeSection 1.3.2 


Since Applesoft checks these locations, so can you. When the differ¬ 
ence between them starts getting close to zero, it’s time to display some 
kind of “don’t worry” message and force housecleaning. Using a state¬ 
ment of the form 

IF (PEEK<il2)*25S + PEEK(111)) 

- (PEEK< 110)*25G + PEEKdOS)) > 2 THEN 
PRINT “PLEASE STAND : Q = FRE (0) 

periodically within your program will force housecleaning to occur and 
will prevent such confusion. 

Since the housecleaning can take as long as several minutes each time 
it occurs, don’t do it too often. It’s best to use FRE (0 ) when you need 
a pause anyway—such as after you write information onto a disk, or 
while the user is reading information on the display screen. 

Debugging Faciiities 

This section details two Applesoft commands used as debugging 
aids: TRACE and NOTRACE. They’re useful when a program isn’t 
behaving as intended and you need to find out why. 


The TRACE Command 

TRACE 


TRACE causes Applesoft to display the line number of each state¬ 
ment it executes. Each iine number dispiayed is preceded on the 
screen by a number sign (#). For example, the program 

10 TRACE 

20 I = I -I- 1 ; I 
30J = J-I-1 !J 
40 GOTO 20 


will display the output 


#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 

#20 

#20 

#30 

#30 

#40 


— I -l- 1 

—two statements on line 20 
= J + 1 

—two statements on line 3 0 
—loop forever 


ad nauseam, or until you press | control | -C, whichever occurs first. 
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Once tracing has been started, it can be canceled only by 


N 0TR ACE statement: see Section 
7.3.2 

Apple He Monitor program: see Apple 
He Reference Manual 


Using TRACE from within a program 


dispiay formatting: see Section 5.2.4 


7.3.2 


• executing the N 0 T R A C E statement 

• restarting the system 

• typing | control | -B to the Monitor program 

As the example above shows, TRACE can be used from within a pro¬ 
gram as well as in immediate execution. A more realistic use in debug¬ 
ging would be to test for some error condition and turn on tracing only if 
the error condition holds: 

IF K > Y THEN TRACE —trace if variable values are 

wrong 

Be sure to remove the T R A C E statements from your program after 
you’ve found and exterminated the bug! 


When the program being traced contains display-formatting statements 
(MT AB, HT AB, T AB, semicolons, commas), line numbers displayed by 
TRACE may appear in a confused fashion or may be overwritten 
entirely. 


The NOTRACE Command 

NOTRACE 


TheNOTRACE command cancels the effects of T R A C E. After this 
command is executed, line numbers are no longer displayed on the 
screen as Applesoft executes them. 
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Chapters 


program planning: see Section 8.1 

coding: see Section 8.2 


8.1 


8.1.1 

Good programs take careful planning 


Specifications define what the program 
does and how 


Programming: Bringing It 
All Together 


Good programs don’t just happen. Programs that are efficient, eco¬ 
nomical, and easy to debug and to modify are the result of careful 
planning. This chapter presents a method to facilitate such planning, 
using as its example a program to calculate postage fees for United 
States mail. A copy of this program is included on the Applesoft Sam¬ 
pler disk; a complete listing can be found in Appendix N. 

Section 8.1, “Planning the Program,” shows how to develop a list of 
program specifications and how to convert the list into a kind of pro¬ 
gram outline. 

Section 8.2, “Writing the Code,” shows how to refine the outline 
developed in Section 8.1 into a final Applesoft program. 

Planning the Program 

Although you can afford to be “quick and dirty” for casual or one- 
time-only applications, you’ll need to do some preliminary planning 
for more serious ones. In general, the more planning you do the more 
efficient and bug-free your finished program will be. 

To demonstrate some of the principles of program planning, this 
chapter develops a program to calculate postage rates on certain 
classes of mail sent in the United States. 


Program Specification 

Program planning begins with deciding what your program is to do or 
what problem you want it to solve. You might want to design a space- 
war game, a tax planner, or a data-base management system. It 
doesn’t matter how simple or how complex the task—whatever it is, 
you have to decide in detail what the program is supposed to do. 

To make writing the program easier, it’s a good idea to begin with a 
list of program specifications. This list specifies what information the 
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What does the program need from the 
user? 


What internal information does the 
program need? 


What won’t the program do? 


program needs, what the program should and should not do, how the 
results are to be presented, and so forth. 

What the Program Needs 

It’s fairly simple to determine what information a postage rates pro¬ 
gram needs. Since the goal is to determine how much it costs to mail 
an item, and since cost is a function of mail class and weight, the pro¬ 
gram needs someone or something to tell it what weight item is being 
mailed in what class. To keep things simple, the program will get this 
information from the program user: 

• The user tells the program the class of mail. 

• The user also tells the program the weight of the item, since pos¬ 
tage rates are based on both class and weight. 

When the program has the weight and class of mail (for instance, 
three ounces of first class), it needs to determine the postage based 
on some scale. It must either calculate the postage with a formula or 
look up the rate in a table stored in the computer’s memory. Since all 
computers are inherently stupid and must be told everything, you 
have to include formulas or tables with which your computer can 
work: 

• The program includes formulas and/or tables of postage rates for 
various weights and classes of mail. 

• The program includes information on the maximum allowable 
weight in each class. 

This last specification is a matter of postal regulations: first class mail 
above 12 ounces is called priority mail and is charged at a different 
rate; 70 pounds is the maximum weight for priority mail; and so forth. 
Program planning, then, calls for information often outside of the pro¬ 
grammer’s immediate purview. That’s why God created libraries and 
telephones—so that programmers could obtain information they 
don’t already have. 

What the Program Will and Won’t Do 

Deciding on the limits of a program is often as important as determin¬ 
ing what the program is supposed to accomplish. United States mail 
has four classes, several types within certain classes, optional extras 
like insurance and various forms of registry, and so forth. To make de¬ 
signing and writing the program simpler, we’ll assume that our pos¬ 
tage is never below first class, and further that we never insure or 
register mail (what fools these mortals...). We’ll also assume that 
packages sent by overnight delivery (express mail) never weigh more 
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than nine pounds and always travel in the same postal zone: 


Humans will be human... 

Give your user clear instructions 


What if the information is invalid or 
inconsistent? 


• The program is limited to express, first class, and priority mail 
(one zone only). 

• The heaviest express mail package will be nine pounds; first 
class and priority mail may be of any weight, up to Post Office 
limits. 

Validating the Data 

Now that the program has information both from the user and from its 
own internal resources (charts of rates and so on), it must check the 
validity and consistency of the information. 

First for validity: does the information the user typed make sense in 
terms of what the program expected? If the program needs a digit for 
the weight of a letter, what should it do if it gets a word? In designing 
any program, it’s important to remember: 

• Most humans do not possess genetic information about what to 
type into computers. 

• Most humans make mistakes. 

The program, then, must display clear instructions telling the user 
what to type (kind of information needed) and what form to use 
(letters, digits, words): 

• The program will display a list of classes of mail on the screen, 
with instructions for the user about what to type. 

• After it gets the class of mail, the program will solicit the weight 
from the user with proper instructions. 

• There will be a mechanism for accepting valid information and 
rejecting invalid information (that is, there are error-handling 
provisions). 

Naturally, if the program rejects invalid information, it must try again 
to get valid information from the user: 

• If information is rejected as invalid, the program will continue to 
solicit information until it gets what it needs. 

Now to consistency: although a user might plausibly ask the cost of 
sending a five-pound package via first class mail, only the program 
knows (by checking its table of limits) that five pounds is too heavy for 
first class. It must notify the user that some other action is called for: 
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How are the results presented? 


What happens when the program is 

finished? 


• If information is rejected as inconsistent, the program will notify 
the user with appropriate recommendations for further action. 

Displaying the Results 

The specifications must also include the form in which the results are 
to be given to the user. In this case we’ll keep it simple: 

• The final calculated postage charge will be displayed on the 
screen with appropriate labeling. 

Finally, the specifications must tell what the program does when its 
job is completed. Here, it will repeat the whole process until the user 
types in some kind of “I’m done” signal: 

• The program will continue to solicit information to calculate new 
postage charges until the user types an “end” signal. 

Reordering the list of specifications into a more logical form, we ob¬ 
tain the final list shown in Table 8-1. 


Table 8-1 Final Specifications for the 
Postage Rates Program 


• The program will display a list of classes of mail on the screen, with instructions for 
the user about what to type. 

• The program is limited to express, first class, and priority mail (one zone only). 

• The user tells the program the class of mail. 

• After it gets the class of mail, the program will solicit the weight from the user with 
proper instructions. 

• The user tells the program the weight of the item. 

• The program includes information on the maximum allowable weight. 

• The heaviest express mail package will be nine pounds; first class and priority mall 
may be of any weight, up to Post Office limits. 

• There will be a mechanism for accepting valid information and rejecting invalid 
information. 

• If information is rejected as Invalid, the program will continue to solicit information 
until it gets what it needs. 

• If information Is rejected as inconsistent, the program will notify the user with 
appropriate recommendations for further action. 

• The program includes formulas and/or tables of postage rates for various weights 
and classes of mail. 

• The final calculated postage charge will be displayed on the screen with appropriate 
labeling. 

• The program will continue to solicit information to calculate new postage charges 
until the user types an “end” signal. 
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interactive program: a program that 
conducts a dialog with the user 


8.1.2 


Lay out your program before you start 
coding 


stepwise refinement: a technique of 
program development in which broad 
sections of the program are laid out first, 
then elaborated step by step 


Table 8-2 Initial Layout of the Postage 
Rates Program 


Repeat 
Display menu 
Accept class 
Accept weight 
Compute charge 
Display results 
until done 


Reviewing the list, you can see that the program’s actions faii into a 
natural chronological order: 

1 . Computer displays prompting messages. 

2. User responds. 

3. Program checks validity of responses. 

4. If any information is invalid, program soiicits new information. 

5. Program checks consistency of responses. 

6 . If any information is inconsistent, program soiicits ciarified 
information. 

7. Program processes validated information. 

8 . Program displays results and goes back to stage 1. 

You’ll find that most interactive programs—programs that carry on a 
“dialog” with a human sitting at the computer—involve most of the 
categories above in roughly the same order. 


Program Layout 

Before rushing to put fingers to keyboard, it’s best to take your plan¬ 
ning at least one step further. Now is the time for program layout. 
Here you plan out the form for each section of the program as de¬ 
scribed in both the specification list and the chronological order list. 

The program layout technique presented here is called stepwise re¬ 
finement. What this means is laying out broad sections of the pro¬ 
gram, then going back and refining each section step by step. 

The Initial Layout 

Table 8-2 shows an initial layout of the Postage Rates program in the 
broadest terms. The layout says that there are five general sections 
to the program {Display menu, Accept class, Accept weight. Com¬ 
pute charge, and Display results), and that the program is to repeat 
this sequence of steps in order until somehow told to stop. 

Each section can now be treated as an independent module, to be 
designed and coded separately. The smaller the chunks of program 
you work with and the more independent each chunk is, the less 
chance for error and the easier the program will be to debug. 
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Refine each module 

Refining the Layout 

Now that we have the program laid out in skeleton form, we can begin 
to put some flesh on the bones. Table 8-3 shows the first refinement, 
in which each of the broad steps in the initial layout is spelled out in 
more detail. 

Table 8-3 First Refinement of the Pos¬ 
tage Rates Program 

Repeat 

Display menu: 

List choices 

Accept class: 

Instruct user how to choose 

Repeat 

Get postage class from user 
until valid menu item 

Accept weight: 

Repeat 

Instruct user how to type 

Get weight from user 
until consistent 

Compute charge: 

Calculate from formula or look up in table 

Display result: 

Format result with dollar sign, trailing zeros 

Label and display result 

Wait for signal from user before proceeding 

until user signals end 


At this point, many programmers would take outline in hand and at¬ 
tack the keyboard. (With an outline?) But a couple of the modules 
need further refinement: both the Accept weight and the Compute 
charge modules need to do specialized processing depending on 
the class of mail specified by the user. The new information in the 
Compute charge module comes from examining postage rate charts. 
First class mail is fairly regular, so a formula can be used to compute 
the charge. Express mail follows no regular pattern, so it’s easier to 
create a table of charges. Priority mail requires a combination of both 
formula and table. The final program layout is shown in Table 8-4. 
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Table 8-4 Final Layout of the Postage 
Rates Program 


Repeat 


Display menu: 
List choices 


Accept class: 

Instruct user how to choose 
Repeat 

Get postage class from user 
until valid menu item 


Accept weight: 

Repeat 

Instruct user how to type 
Get weight from user: 

Check validity of response 
Express? 

If item more than 9 pounds 
then suggest alternative 
First class? 

If item more than 12 ounces 
then suggest alternative 

Priority? 

If item less than 12 ounces 
then suggest alternative 

If item more than 70 pounds 
then suggest alternative 
until valid and consistent 


Compute charge: 

Express? 

Look up charge in table 
First class? 

Calculate charge from formula 
Priority? 

If item less than 10 pounds 
then look up charge in table 
otherwise calculate charge from formula 


Display result: 

Format result with dollar sign, trailing zeros 

Label and display result 

Wait for signal from user before proceeding 


until user signals end 
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Writing the Code 

Now that you’ve refined the program layout to a sufficient level of 
Use the layout as a guide while writing detail, you’re finally ready to start writing code. The layout is only a 

code guide; it isn’t the last word. As you write and test the actual program, 

you may find you need to make changes in your original design. 
That’s perfectly all right; use the layout to keep you on track. 


Methodical program development 

makes programs easy to debug and 
modify 


What follows in this section represents one way to turn the outline 
into a working program. It isn’t the only way—a hundred program¬ 
mers would produce a hundred different programs for the same task. 
It does, however, work; and because it’s been developed in an or¬ 
derly, methodical way, it’s also logically organized and easy for a hu¬ 
man reader to foliow. This is an important consideration, because it 
makes the program easy to debug and easy to modify. (Almost all se¬ 
rious programs need to be modified at some time or other, often by 
someone other than the original programmer.) 


The author makes no warranties, either Hysterical Note: Any resemblance between the following program and 
express or impiied ... true top-down structured code is purely coincidental and probably hallu¬ 

cinatory. The perceiver of such a resemblance is advised to seek psy¬ 
chiatric aid promptly. 


8.2.1 Preliminaries 

Your program should begin with a block of R E M statements identify¬ 
ing the program and describing what it does. Most programmers add 
their own name and the date of the program’s current version: 


10 

REM 

POSTAGE RATES 




—name of program 

20 

; 


—colon leaves line empty 

30 

REM 

DETERMINES POSTAGE FEES 




—what program does 

40 

REM 

FOR 

EXPRESS» 1ST CLASS* 

50 

REM 

AND 

PRIORITY MAIL 




—empty line inserted by embed- 


ding | control | -J (linefeed) 
at end of R E M statement in 
line 50 


GO REM M2 9/01/82 

—number and date of this 
version 

70 REM BY JOHN SCR IBBLEMONGER 

—programmer’s credit line 
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8.2.2 Display the Menu 

Now you can refer to your outline and base your code directly on it. 
Notice the R E M statements introducing the different sections. All the 
comments marked here by dashes (—) could also be included as 
REM statements: 


10 0 

REM MENU 

OF POSTAGE CLASSES 

— 1 CONTROL |-J here 

no 

HOME 

—begin with a clear screen 

120 

TITLE$ = 

"POSTAGE RATES" 

130 

PRINT 


140 

HTAB 21 - 

LEN (TITLES) / 2 

—formula to center title 

150 

PRINT TITLES 

ISO 

OTAB G 


170 

PRINT "1. 

EXPRESS" 

180 

PRINT "2, 

FIRST CLASS" 

190 

PRINT "3. 

PRIORITY" 

200 

PRINT 


210 

PRINT "4, 

END THE PROGRAM" 

—the escape hatch 


8.2.3 What’S The Postage Class? 

This section finds out what mail class the user wants to use. Note 
the use of I control | -J, the line feed character, to set off the R E M 
statements for easier reading (line 300): 


300 

REM 

—1 CONTROL |-J here 


GET CLASS 

OF MAIL 

— 1 CONTROL |-J here 

310 

MTAB 14 


320 

PRINT "Press 

the nufflbe r of your 


choice:" 5 

—semicolon keeps response on 
same line 

330 

GET CS 

—only one keypress needed; 
cuts down on error possibili¬ 
ties. Note use of string variable 
to get number; avoids type 
mismatch errors 

335 

REM 

—1 CONTROL i- J here 


CHECK FOR 

OALIDITY 


—another | control | -J (last 
time this is noted) 
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340 

350 


360 

370 

380 


390 


IF C$ = "a" THEN END 

—end program if user types a 4 
IF OAL (C$) > 0 AND MAL (C$) < 4 
THEN 380 —skip next two lines if valid 

choice typed 

PRINT CHR$(7) ; CHR$(7) 5 

—beep twice to get attention 
—response was invalid; try 
again 

—since choice accepted via 
G E T, it isn’t displayed on the 
screen. Display it back to user 
C = MAL ( C $) —need this value later to deter¬ 

mine what section of program 
to branch to for proper 
processing 


GOTO 330 
PRINT C$ 


8.2.4 What Does It Weigh? 

Now the program asks the user for the weight of the letter or package. 
The program makes sure that the user follows the instructions and 
types a number for the weight and a symbol (0 or P) for ounces or 
pounds. Notice that the program accepts both the numeric weight of 
the item and the ounce/pound designation in the same string (line 
530). 


500 RErt 

GET WEIGHT OF ITEM 


505 MTAB 16 


510 

PRINT 

"PI 

ease 


n u ffl b 

e r 

plus 


(for 

PO 

u n d s 


k e y : 

" 5 


520 

CALL - 

868 


530 

INPUT 

" " ; 

W$ 

5ao 

Wl$ - 

RIGHT$ 


enter the WEIGHT - a 
an 0 (for ounces) or a P 
) - and press the RETURN 
—prompting message to tell 
user what information to type 
and how to type it 
—clear to end of line; useful to 
erase any errors that might be 
typed 

—semicolon suppresses ques¬ 
tion mark 
(W$ » 1) 


—rightmost letter should be 
either 0 or P; use it later to see 
if weight is consistent with 
postal regulations 


194 


Programming: Bringing It AM Together 


I 






—how many ounces or pounds? 


550 W = OAL (W$) 

555 REM 

WAS ENTERED WEIGHT OALID? 

5B0 IF W > 0 AND (W1$="D" OR Wi$="P") 
THEN 710 —if a weight was typed, and if 

last character was either 0 for 
ounces or P for pounds, then 
proceed 

570 PRINT CHR$ (7)5 CHR$ (7) 

—beep twice to get attention 
580 GOTO 500 —entry was invalid; try again 

If the program has progressed this far, then everything typed by the 
user is valid from the computer’s point of view. However, the user’s 
choices still may not be consistent with postal regulations or the pro¬ 
gram’s limitations. First class letters must weigh less than 12 ounces, 
the program can’t handle express mail above a certain weight, and 
so on. This section of code uses the value of variable C (set in line 
3 9 0) to direct control to the proper subroutine to check for 
consistency. 

700 REM 

CHECK CONSISTENCY 

710 ON C GOSUB 10000» 11000» 12000 

—branch to appropriate subrou¬ 
tine to see if weight typed is 
within postal rules or program 
limitations for mail class 
chosen 

720 IF NOT EFLAG THEN 910 


—if no inconsistency detected in 
subroutine then proceed with 
processing 


730 

GOSUB 

GOOOO 

: REM KEYSTALL 

—wait for user to acknowledge 
message 

740 

EFLAG 

= 0 

—clear error flag set in 
subroutine 

750 

CLEAR 


—reset all variables, clear 
arrays, etc. 

7G0 

GOTO 1 

00 

—restart program loop 


Writing the Code 


195 













8 . 2.5 Compute the Charge 

Now that everything checks out all right, the program can proceed to 
caicuiate the postage. The calcuiation is different for each of the 
three classes of postage, so there are three separate calculating rou¬ 
tines. Again, what routine the program goes to depends on the value 
of C, the number representing the postal class chosen by the user. 

900 REM 

FIND APPROPRIATE CODE FOR 
PROCESSING —everything is valid and consis¬ 

tent; now program can solve 
for the postage rate! 

910 ON C GOSUB 1000» 2000» 3000 

—branch to proper calculating 
routine 

920 GOSUB BIOOO : REM FORMATTER 

—format result for display 

930 PRINT 


8.2.6 Display the Results 

It’s finally time to display the result! 

935 REM 

DISPLAY RESULTS 

SaO PRINT "POSTAGE NEEDED: T$ 

—finally, the postage due! 

950 GOSUB GOOOO ; REM KEYSTALL 

—don’t go on until user is ready 
9G0 CLEAR —prepare for restart... 

970 GOTO 100 —...anddoit. 


8 . 2.7 Calculating Routines 

The foilowing three subroutines do the actual rate calculations, 
based on formulas, tables, or both. The rates for express mail are 
fairly straightforward; they are based on a table created in the ex¬ 
press mail consistency-checking routine at line 10 0 0 0. First class 
rates couldn’t be simpler; a little arithmetic is all that’s needed. Prior¬ 
ity mail is another story, however; when you get to it, you’ii find an 
explanation. 

999 REM 

SUBROUTINES BEGIN HERE 
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1000 REM 


’m not making this up... 


EXPRESS MAIL CALCULATION 

W = INT (W + .30) 

—weight must be increased to 
compensate for fractions; 
postal rates read “NOT MORE 
THAN X POUNDS” 

T = R (W> —rate array filled in express mail 

consistency-checking routine 
(line 10000) 

RETURN —end routine 

REM 

FIRST CLASS CALCULATION 

2010 T = .20 + INT (N -I- .93 - 1) * .17 

—first class rate is 20 cents first 
ounce plus 17 cents for each 
additional ounce or portion 
thereof (April, 1982 rates) 
2020 RETURN —end routine 

Although there is something approaching a pattern to priority mail 
charges, the pattern is obscure at best. This is especially true for the 
first ten pounds. Pounds 1 through 5 are charged by the half-pound: 
pounds 6 through 10 are full-pound charges. It’s simpler and quicker 
to use a table for these charges (lines 3 0 3 0 to 314 0) than to figure 
out a formula. 

Weights over 5 pounds follow a more regular pattern than the first 5; 
they are all charged in full-pound increments. Furthermore, each five 
pounds costs $2.38. Unfortunately, the cost for pound 6 is different 
from the cost for pound 7, and so on. What it boils down to is that 
5-pound lots can be charged at the same rate (line 3170), and 
anything that isn’t a multiple of 5 must be looked up in a table (lines 
3180 to 3220). 

If all this strains credulity, refer to United States Mail Service poster 
103, November 1981. 

3000 REM 

PRIORITY MAIL CALCULATION 

3010 W = INT (W -H .99) 

—compensate for partial ounces 
or pounds 


1010 

1020 

1030 

2000 
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3020 IF W > 10 THEN 3ISO 

—go to line 31G 0 for weights 
greater than 10 pounds 
(ounce weights converted to 
pounds in consistency subrou¬ 
tine starting at line 12000) 

3025 REM 

PRIORITY RATES TO 10 POUNDS 


3030 

3040 

3050 

3060 

3070 

3072 

3078 

3080 

3090 

3100 

3110 
3120 
3130 
3140 
3150 
31 GO 


= 1 THEN T = 2.24 
1 AND W <= 1.5 THEN 
T = 2.30 —rates in half-pound increments 

IF W > 1.5 AND W <= 2 THEN 
= 2.54 

> 2 AND W <= 2.5 THEN 
= 2.78 

> 2.5 AND W <= 3 THEN 
T = 3.01 

IF W > 3 AND W <= 3.5 THEN 
T = 3.25 

IF N > 3.5 AND N <= 4 THEN 
T = 3.40 

IF W > 4 AND W <= 4.5 THEN 
T = 3.73 

IF W > 4.5 AND W <= 5 THEN 
T = 3.97 

IF W > 5 AND W <= 6 THEN T = 4.44 

—rates by the pound now! 


IF W 
IF W 


T = 
IF W 
T = 
IF W 


= 7 THEN T = 4.92 
= 8 THEN T = 5.39 
= 9 THEN T - 5.87 
9 THEN T = 6.35 

-branch to R E T U R N statement 


G AND W 

7 AND W 

8 AND W 


IF W 
IF N 
IF W 
IF W 

GOTO 3240 
REM 

PRIORITY RATES FOR ODER 10 POUNDS 


3170 

T1 

= INT 

(W / 

5 

3180 

W1 

= W - 

INT 

(N 


- 1) * 2.38 + 3.97 
—first 5 pounds cost $3.97; each 
added 5 pounds cost $2.38 
/ 5) * 5 


—how many odd pounds are 
there (pounds that are not 
multiples of 5 and must be 
charged at a special rate)? 


3190 

IF 

W1 

= 1 

THEN 

•J* ^ _ 

.47 

3200 

IF 

W1 

_ ^ 

THEN 

T2 = 

.95 

3210 

IF 

W1 

= 3 

THEN 

T2 = 

1.42 
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3220 IF W1 = a THEN T2 = 1,30 

3230 T = T1 + T2 —add the 5-pound-multiples rate 

to the odd-pounds rate 

3240 RETURN —end routine 


.2.8 Consistency-Checking Routines 

The next three routines make sure that first class letters aren’t too 
heavy, that the requested rate can be calculated by the program, and 
in general that the program can deliver what the user wants. The ex¬ 
press mail routine begins by loading its rates into a table (it gets the 
rates from a DATA list; DATA lists are excellent places to store infor¬ 
mation you might need in a program); then it checks to see if it has a 
rate for the package being sent. First class just makes sure that the 
package weighs 12 ounces or less; that’s the maximum weight for a 
first-class item. Priority mail also has an easy job; it just makes sure 
the package weighs more than 12 ounces but not more than 70 
pounds. 


10000 REM 

EXPRESS MAIL CONSISTENCY CHECK 


10010 

1 0020 

10030 

10040 

10050 


DATA 3,35f 3,35» 3,55* 3,30> 


10,30 f 10,B5 » 1 1,00 > 11,40* 
11,75* 0 —express mail rates; 0 at end Is 

“last item” flag 

X = 0 —set up counter to check how 

many rates are read from 
DATA list 


X = X -I- 1 —increment counter 

READ R (X) —put price into proper array 

element 

IF R (X) - 0 THEN 10070 


—price of 0 marks end of list 
lOOBO GOTO 10030 —get next price 

10070 X = X - 1 —X includes count of “last item” 

flag from 1005 0; subtract it 
from count since it’s a 
“dummy” item 

10080 IF Wl$ = "P" THEN 10100 

—next line is for ounces only 
10030 W = W / 13 —convert ounces to pounds 

10100 IF W<=X THEN 10140 

—if weight in pounds is covered 
by the rate chart, then go 
ahead 
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10110 

10120 


10130 


10140 

11000 


11010 

11020 

11030 


11040 

11050 


HOBO 

12000 


12010 

12020 


12030 

12040 


12050 

120B0 


12070 

12080 

12090 


PRINT 

PRINT CHR$ (7)5 CHR$ (7)5 "TOO 

HEAMY FOR MY TABLES - PLEASE CALL 
THE POST OFFICE" 

—sorry; can’t help you 

EFLAG = 1 —set flag indicating inconsistent 

weight/type: will be checked at 
line 720 

RETURN —end routine 

REM 

FIRST CLASS CONSISTENCY CHECK 

IF Wl$ = "0" AND W < 12.01 

THEN llOBO —OKif not more than 12 ounces 

PRINT 

PRINT CHR$ (7)5 CHR$(7); "TOO 
HEAOY FOR FIRST CLASS" 

—sorry—inconsistent! 

PRINT "TRY PRIORITY MAIL" 

—suggest alternative 

EFLAG = 1 —set flag indicating inconsistent 

weight/type; will be checked at 
line 720 

RETURN —end routi ne 

REM 

PRIORITY MAIL CONSISTENCY CHECK 

IF Wl$ = "P" THEN 12090 

—if in pounds, then skip down 
IF W > 12 THEN 12080 

—skip down if weight is between 
12 and 16 ounces 

PRINT 

PRINT CHR$ (7)5 CHR$ (7)5 

"TOO LIGHT FOR PRIORITY MAIL -" 

—too light! 

PRINT "TRY FIRST CLASS" 

—suggest alternative 

EFLAG = 1 —set flag indicating inconsistent 

weight/type: will be checked at 
line 720 

GOTO 12150 —branch to end of routine 

W = W / IB —convert ounces to pounds 

IF W <= 70 THEN 12150 

—final check: is item on the 
charts? 
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12100 

PRINT 



12110 

PRINT 

CHR$ (7) 

5 CHR$ (7)5 


"TOO 

HEAOY FOR PRIORITY MAIL -" 




—off the charts 

12120 

PRINT 

"TRY ONE 

OF THE AIR EMPRESS 


COMPANIES" 

—too big for the Post Office! 

12130 

EFLAG 

= 1 

—set flag indicating inconsistent 




weight/type; will be checked at 
line 720 

12150 

RETURN 


—end routine 


8.2.9 The “Keystair Routine 

The “keystall” routine interrupts execution of the program and waits 
for the user to press a key before going on. The GET statement in 
line B 0 0 4 0 actually does the waiting; when the user presses a key, 
the program continues. What key the user presses doesn’t matter— 
the program doesn’t care what value is assigned to A$. 

50999 REM 

UTILITY ROUTINES 

—routines useful for various 
tasks but ancillary to rest of 
program 


BO 000 

REM 

KEYSTALL 

—routine to interrupt program 
until user presses a key 

BOO 10 

UTAB 24 

—move cursor to screen bottom 

B0020 

INMERSE 

—set text to appear black-on- 
white 

B0030 

PRINT "PRESS 

RETURN TO GO ON..."5 

BOO 40 

GET A$ 

—wait for keypress 

BOO 50 

NORMAL 

—restore ordinary white-on- 
black 

BOOBO 

RETURN 

—end routine 


8 . 2.10 The Formatting Routine 

After the postage charge is calculated, the program branches to this 
final subroutine. Here the final result is checked to see how it will look 
when it is displayed. Does it have a decimal point? Applesoft sup¬ 
presses trailing zeros after a decimal point, but people are used to 
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Find your own style 


(Funny—I don’t feel comforted...) 


seeing them when dealing with dollars and cents. The formatting 

subroutine adds trailing zeros as needed. 

GIOOO REM 

MONEY FORMATTER 

—adds zeros after the decimal 
point where needed 

BIO 10 T$ = STR$ (T) —turn the calculated postage 

fee into a string 

G1020 IF T = INT (T) THEN T$ = T$ + 

" . 0 0" —if charge is in whole dollars, 

add a decimal point and two 
zeros 

B1030 IF ABC (RIGHTS (T$»2)) = HG THEN 

T$ = T$ + "0" 

—if second character from the 
right is a decimal point (ASCII 
code 4B) then number has 
only one digit to right of deci¬ 
mal—so add a " 0" to the 
string 

B1040 RETURN —end the routine 


8.3 Final Advice to the New Programmer 

The program planning methods discussed and demonstrated in this 
chapter won’t necessarily work for everyone. Different people have 
different programming styles, and some people won’t be comfortable 
with the (perhaps) coldly logical model presented here. What’s im¬ 
portant is to find a style that works for you. Programming is a logical 
art; it shouldn’t be a confining one. Be as creative as your own inter¬ 
nals will let you, remembering that poets also plan. 

Keep in mind as you learn to program, please, when a bug is as hard 
to find as cheap gas, that deep down at the bit level—down where the 
computer deals with the only things it really understands—there are 
only zeros and ones. 
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Index 


A 

ABS function 38,215 
absolute value 38,215 
addition 32,36,86 
American National Standards 
Institute (ANSI) 3 
American Standard Code for 
Information Interchange, see 
ASCII 

ampersand character (&) 246 
AND 35,175 
animation 150 
annunciators 131,262,263 
ANSI: see American National 
Standards Institute 
Apple He 80-Column Text Card, see 
80-Column Text Card 
arctangent 41,216 
argument of functions 37,38,125, 
173,179 

argument variable 44 
arithmetic functions 38 
arithmetic operators 31 
array(s) 26,29, 77ff, 217,228,248, 
249, 268, 275ff, 293ff, 298 
dimensions 79,80 
elements 29,77,269 
names 29, 77 
storage 179 
variables 275ff 
arrow keys 18,20 
A SC function 215 
ASCII (American Standard Code for 
Information Interchange) 19,82, 
215, 241 ff, 258 

assignment statement 30,215, 
224, 251,296 
asterisk (*) 32 
ATN function 41,216 
auto-repeat 19,20 


B 

backslash character (\) 4,18 
BAD SUBSCRIPT error 79,248 
bell character ( IcqntrqlI -G) 130 
B L 0 A D command 158 
body of loop 55 
booting 96,112 
branch 49ff,220 
conditional 51 
unconditional 50,220 
built-in arithmetic functions 38ff 

c 

CALL statement 71,136,216,249, 
253ff, 281,294 

CAN'T CONTINUE error 248 

[CAPS LOCKI key 4 

caret (") 31 

cassette input 110 

cassette output 131,264 

Celsius 44 

character codes 82 

CHR$ function 91,216 

CLEAR Command 9,30,129,216, 

294 

colon(:) 5,98ff, 105,106,177,192, 
246, 267, 296, 301 
color, see display color 
COLOR = statement 137,216 
comma(0 98ff, 105,113,114,115 
commands, see names of 
commands 

concatenation 83,84,100,251, 

295 

conditional branch 51 
constants 268 

CONT command 16,17,73,216, 
247,248 

control characters 100,101,241 
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[CONTROL I key 15,16,18,241 
98,107 

-B 176,177,181 
-C 15ff,50,58,69,72, 
98,107,159,180,216 
-G 130 
-H 100,107 
- J (line feed character) 
192,193,216,301 
-M 100,107 
- IRESETI 13-17,96,112, 
161,162,166,171 
-S 15 

-X 18,100,107 

control 

stack 10,62ff,71,227,265 
statements 49ff 
COS function 40,217 
cosine 40,217 
crossed loops 60 
current input device 104,223 
current output device 10,113,224, 
228 

cursor 4,18ff, 97,113,115,119ff, 
220ff, 232, 234, 253, 254 
cursor control 287-288 

D 

DATA statement 103,105,108, 
217,228,229,250 
debugging 11,180 
D E F F N Statement 44,177,217 
249 

deferred execution 4,5,9,247 

degrees 44 

DEL command 6,7,217 

I DELETE I key 7 

DIM Statement 79,217,251,293, 

OQC OQQ 

disk i2ff, 112,156,230 
Disk Operating System (DOS) 12, 
14,16,105,157,176, 265, 298 
display color 137ff, 160,216,220ff, 
231 

display screen 111 
division 32 

DIVISION BY ZERO error 248 
dollar sign ($) 26,29,82,88,251, 
259 

DOS (see Disk Operating System) 
double quotation marks (") 28,81, 
99,102,270 

I DQNN-ARRON I key 18,19,241 
DRAW statement 151,155,156, 

160,161,162,163,164, 218,230, 
231 


e 42 

editing 287-288 
Eighty-Column Text Card 4,112, 
114,115,119,124,125,127,222, 
254, 287ff 

END Statement 17,73,216,218, 
251,269, 294 

equal sign (=) 30,34,44,129,137, 
145,163, 246 
equal to (=) 34 
error 

codes 68,69,247ff 
messages 247ff 
error handling routines 67ff, 229, 
247, 264 

restoring normal 71 
escape mode 19,287 
Fe^ key 20,242 
-0 20,255 
-A 20 
-B 20 
-C 20 
-D 20 
-E 20 
-F 20,255 
-I 19,20 
-J 19,20 
-K 19,20 
-M 19,20 
exclusive-or 175 
execution of program 16 
EXP function 42,218 
expansion slot 96,111 
exponential 42,218 
exponentiation 32 
expressions 31 ff 
EXTRA IGNORED message 99, 
105 

F 

Fahrenheit 44 
false 33ff 

FILE NOT FOUNDerror 14 
FLASH statement 127,128,218, 
226 

floating-point accumulator 173 
FN keyword 45,219 
FOR statement 55ff, 219,225,271 
FORMULA TOO COMPLEX error 
248 

FP command 291 
fractions 33 
FRE function 178,220 
free space 275 
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full-screen graphics 136,138,143, 
144,146, 221,260 
function names 44 
functions 37ff, 173,177,229 
argument of 37,38,125,173,179 
built-in arithmetic 38 
call 37,38,45 
names 44 

user-defined 44-45,217 
ABS 38,215 
ASC 215 
ATN 41,216 
CHR$ 216 
COS 40,217 
EXP 42,218 
FRE 178,219 
I NT 39,223 
LEFT$ 100,223,249 
LEN 224 
LET 215 
LOG 42,224,249 
MID$ 100,225,249 
PEEK 130,131,177,178,180, 
247, 249, 253ff 
POL 109,227 
POS 125,228 
RIGHT$ 100,229,249 
RND 43,229 
SCRN 141,231 
SGN 39,231 
SIN 40,231 

SPC 113,120-121,231,249 
SQR 40,232,249 
STR$ 232 

TAB 113,120,121,123,126, 
181,232, 233,249,254 
TAN 4,233 
USR 172,233 
OAL 102,105,233 

G 

GAME I/O connector 109 
GET statement 16,19,104,220, 
249 

G 0 S U B statement 61 ff, 220,227, 
229, 251,293 

GOTO statement 50,53,64,71, 

220, 251,265, 293 
GR statement 136,140,220,258, 
259,261 

graphics 119,135ff, 258 

greater than (>) 34 

greater than or equal to (> = or = >) 

34 

ground loop 297 


H 

hand control 109,262 
hand control connector 109,131, 
262, 263 

HC0L0R= statement 145,160,220 
HGR statement 143,145,149,161, 
162, 220,258,259 
HGR2 statement 144,145,149, 
161,162, 221,259 
high-resolution graphics 136,140ff, 
150,176ff,218, 220ff, 230, 261 
HIM E M; statement 149,156,165, 
176,179,221,250,275,299 
HLIN statement 139,221 
HOME statement 221,254 
HPLOT statement 146,161,218, 
222, 262 

HTAB statement 120,122,126, 
181,222,254,256 
HumptyDumpty 19 

/ 

IF . ♦ ♦ THEN Statement 33,36,52, 

222, 248, 251,267, 294 
ILLEGAL DIRECT error 249 
ILLEGAL QUANTITY error 40, 

42, 52, 66, 86ff, 92, 97,109,112, 
121ff129,138ff, 146,147,161ff, 
170,171,175ff, 249 
immediate execution 4, 7,9,257 
IN#statement 96,223 
index variable 55ff, 219,225,271 
infinite loop 58 
Input 95,223 
numeric 100 

Input Anything Routine 102 
INPUT statement 16,17,97, 

102, 223, 249,294 
Input/output 93ff 
string 99 

I NT function 39,223,291 
Integer 

constants 270 
part 39,223 

variables 26,27,44,58,270, 
275ff 

Integer BASIC 260,291 
INUERSE statement 126,128, 

223, 226 

j 

J M P (Jump) instruction 173,233 
JSR (Jump to Subroutine) 
instruction 173,174,246 
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K 

keyboard 96,258 
keyword tokens 280ff 
keywords 4 

L 

LEFT$function 86,100,223.249 
I LEFT-ARRQMI key 18,19,100, 

241 

L E N function 83,85,224 
LET statement 215,224 
less than (<) 34 

lessthanorequalto(< = or =<) 34 
line feed character ( I controli - 
192,193,216, 255 
line numbers 5ff, 50,51,64,65, 70, 
180, 220, 226,232, 233,251,265, 
267, 293,294 

LIST Command 7,10,224 
LOAD Command 14,110,224,298 
LOG function 42,224,249 
logarithm, natural 42,224 
logical operators 35,54 
logical values 33,36,54 
L 0 ME M : statement 177,225,250 
loops 10, 55ff, 219,225,250, 270, 
296 

body 55 
crossed 60 
nested 59 

low-resolution graphics 135,216, 
220,221,231,234,258,261 

M 

machine language 172,176,177, 
179,216,221,233,246 
mask 174 
MAT functions 296 
memory allocation 25,275 
memory management 176 
MID $ function 87,100,225,249 
minus sign (-) 36,105 
mixed graphics and text 119,136, 
138,140,141,143,146,220,260 
Monitor program 16,7 155ff, 172, 
173,176,177,181 
multidimensionai array 80 
multiple input 98 
multiple statements per line 5 
multiplication 32 

N 

natural logarithm 42,224 
nested loops 59 
nested subroutines 62 


NEW command 9,30,150,177,225 
NEXT statement 55ff, 225,271, 

294 

NEXT WITHOUT FOR error 10, 
60,249 

NORMAL Statement 126,128,226 
NOT 35,54 

not equal to (<> or ><) 34 
NOTRACE command 181,226 
null character ( lCQNTRQLI -§) 98, 
100,101,105 

null string 9,12,28,30,81,82,88, 
97,98,100,106, 251,294 
number formats 117 
number sign (#) 96,111,180,246 
numeric constants 117,283 
numeric input 100 

o 

ON . . . GOSUB Statement 65,226, 
249 

ON... GOTO Statement 51,226, 
249 

on-screen edit 17 
ONERR GOTO statement 68,72, 
226, 229,247,239,264, 265 
lOPEN-APPLEI key 110,262 
operators 31 ff 
arithmetic 30 
logical 35,54 
precedence of 36 
relational 33,54 
OR 34,54 

OUT OF DATA error 106,250 
OUT OF MEMORY error 60,64, 
177,178,250, 299 
output 111 

OVERFLOW error 90,91,250 

P 

parentheses 37,250,276 
POL function 109,227 
PEEK function 68,70,110,130, 

131,170,177,178,180,227,247, 
249, 253ff, 294 
percent character (7.) 26,28 
period (.) 105 
PLOT statement 138,227 
plotting vector 150ff 
plus sign (-f) 36,84,105,295 
point of call 61,64 
pointer 275 

POKE statement 71,72,129ff, 136, 
143,149,155,156,159,170ff, 
227,249,253ff, 294 
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POP statement 66,227 
POS function 125,228 
pound sign (#) 96 
PR# statement 10,111,228 
precedence 36 

PRINT statement 105,113ff, 120, 
121,223, 226,228,231,232, 254, 
267 

TAB used in 121ff 
printer 10,111 
program 275 
execution 16 
layout 189 
lines 3 
planning 185 
specification 185 
prompt character (3) 4,16,119, 
247 

prompting message 97,294 
pure cursor moves 19 

Q 

question mark (?) 97,116,294 

R 

radians 40,41,44 
RAM (random-access memory) 
176,179 

random numbers 43,229 
READ statement 105,108,207, 

217.129.250 

real variables 25,27,44,58,270, 
275-277 

RECALL Statement 110,298 
REDIM'D ARRAY error 79,250 
REENTER message 99,100 
relational operators 33,54,82 
REM statement 7,229,267 
reserved words 27,245-246,276 
I RESET I key 16 
reset vector 16 

restarting the system 96,112,176, 
181 

RESTORE statement 106,108, 

229.250 

Restoring Normal Error Handling 
71 

RESUME statement 69,70,229, 
249, 265 

return address 63,66,227 
I RETURN I key 4,6,10,13,16,18, 

100,104,158,165, 219, 241,293 
INPUT Statement use 97,98 
RETURN statement 61 ff, 220,227, 
251 


RETURN NITHOUT GOSUB 
error 64,67,251 
right bracket (3) 4,16,119,247 
RIG H T $ function 100,229,249 
IRIGHT-ARRQNI key 18,19,241 
RND function 43,229 
R 0 T = statement 160,164,230 
rotation 230 
rounding 39 

RTS (Return From Subroutine) 174 
RUN Command 12,14,30,108, 
145,150, 230,294 

s 

SAVE Command 13,131,230,297 
scale factor 230 

SCALE = statement 160,163,164, 
230 

scientific notation 43,91,118,283 
SCRN function 141,231 
scrolling 253 
seeding 43 

semicolon (?) 113ff, 122,267,269 
SGN function 39,231 
shape definition 150 
shape table(s) 150ff, 230,231,234, 
299 

index 153 
loading 154ff 

SHLOAD statement 110,156,158, 
165,231,299 
sign of a number 39,231 
simple variables 275- 277 
SIN function 40,231 
sine 40,231 
slash (/) 296 
soft switches 253,259 
I SOLID-APPLEI key 110,262 
spacebar 19,21 
space character 99,101,105,231 
SPC function 113,120-121,231, 
249 

speaker 130,264 
SPEED statement 128,231 
S 0 R function 40,232,249 
square root 40,232 
statements 3,223,269 
see also names of statements 
step value 57ff 
stepwise refinement 189 
STOP statement 17,73,216 
STR$ function 89,232 
string(s) 28,81,113,229,232,233, 
270,275ff, 293,295 
comparison 82 
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constants 28,81,83 
conversion 89 
input 99 
null 28 

pointers 275-277 
storage 179 

variables 26,28,44,83,102, 
104,105,107 

STRING TOO LONG error 84, 
85,114,251 

subroutlne(s) 10,61ff, 171,229, 
250,269, 270, 276 
call 61 

execution 220 
nested 62 
subscripts 29,77,79 
substrings 86,295 
subtraction 32,36 
syntax definitions 235ff 
syntax error 13,14,54,58,105, 
107,143ff, 166,251 

T 

TAB function 113,120,121ff, 126, 
181,232,249,254 
TAN function 41,233 
tangent 41,233 

tapecassette 13,14,110,156,158, 
165,228,230,231,297ff 
termination 218,232 
text 142,253 

window 115,119ff, 129,136,143, 
221,253ff 

TEXT statement 119,136,143, 
233,258 

TRACE command 180,181,226, 
233,294 

trigonometric functions 40-41 
true 33ff 

truncation 28,39,51,65,86,88, 
91,117,120ff, 283 
TYPE MI SNATCH error 87,88, 
251 

u 

unconditional branch 50,220 
UNDEF'D FUNCTIONerror 251 
UNDEF'D STATEMENT error 12, 
50,51,64. 251,268 
I UP~ARRQM I key 18,19,241 
user-defined function 44-45 
US R function 172,233 
utility strobe 131,261,264 


V 

MAL function 83,86,90,102,105, 

107.233 

validation of data 187 
values, logical 33,54 
variable(s) 25ff, 51,97,98,177, 
216, 268 
argument 44 
Index 55,57,58,60 
integer 26 27,44,58 
name 26,293 

real 25, 27,44, 58,270,275ff 
string 26,28,44,102,105 
ML IN Statement 140,234 
MTAB Statement 119,120,124, 
181,234, 256 

w 

WAIT Statement 174,234,249 
wraparound 4,120,122 

X 

XDRAW statement 151,161 ff, 230, 

231.234 

XPLOT statement 246 

Y 
Z 

zero page 278 


Cast of Characters 

" (double quotation marks) 28,81, 
99,102,270 

(number sign) 96,111,180,246 
$ (dollar sign) 26,29,82,88,251, 
259 

7 ., (percent character) 26,28 
&: (ampersand) 246 
( ) (parentheses) 37,250,276 

* (asterisk) 31,32 

+ (plus sign) 31,36,84,105 
, (comma) 98ff, 105,113ff 
- (minus sign) 31,36,105 

♦ (period) 105 

/ (slash) 31,296 
: (colon) 5.98ff, 105,106,177,192, 
246, 267, 296,301 

; (semi-colon) 113ff, 122,267,269 
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< (less than) 34 

< = or = < (less than or equal to) 34 
= (equal sign) 30,34,44,129.137, 

145,163, 246 

> (greater than) 34 

> = or = > (greater than or equal to) 34 

< > or > < (not equal to) 34 

? (question mark) 97,116,294 
3 (right bracket) 4,16,119,247 
\ (backslash) 4,18 
*• (caret) 31 

80-Column Text Card 4,112ff, 119, 
124,125,127,222,254, 287ff 
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